|
Claude Desktop App can ask, confirm, and collect input — as real native desktop dialogs.
|
When Claude Desktop App has a question that's really a pick between options, you have to type the answer in prose. When it wants your go-ahead before touching production, you get a blue Yes/No box — and nothing more tailored.
There's a better way.
aiui lets Claude Desktop App open real, native dialogs on your machine — macOS and, since 0.10.1, Windows:
- "Which of these three deploy strategies?" A window with three cards, each with context. One click. Done.
- "Shall I drop the production
orderstable?" A red destructive button with a clear warning. One click. - "Fill in name, role, start date." A clean form instead of a typing-heavy chat exchange.
- "Rank these five tickets in the order you want them." Drag to reorder, the order comes back as a clean list.
- "Here's the flow I'm proposing — does it look right?" A real diagram (Mermaid → SVG) instead of ASCII boxes-and-arrows that collapse into nonsense in proportional fonts.
The agent gets your answer as structured data and keeps going. No side conversations, no throwaway web dashboards cluttering your system — just a familiar window from your own operating system that does what it looks like.
Running Claude Desktop App directly on your Mac or Windows PC? aiui plugs in.
Running it over SSH on a remote machine (dev box, project VM)? aiui automatically sets up a tunnel so the remote agent can pop dialogs right on your own desktop. Register the host once in settings; from then on it just works.
No Terminal. No Homebrew. No Python. No uv.
- Download aiui.app (DMG, Apple Silicon).
- Drag into
Applications. This step is not optional: launched straight off the mounted DMG or out of~/Downloads, macOS runs aiui from a throwaway copy that disappears when you quit it. aiui notices, refuses to register itself with Claude, and shows you a banner saying so — rather than writing a path that is dead by the next tool call. - Launch it once from Finder.
- Download the installer
—
aiui_<version>_x64-setup.exe. - Run it. Windows will warn you: a blue "Windows protected your PC"
box appears, because the installer carries no Authenticode signature.
Click More info, then Run anyway. This is expected, not a sign
that anything is wrong — a code-signing certificate is on the list, and
until it lands every aiui installer triggers this. The download page
ships a signature file (
.exe.sig) next to the installer; that is what aiui's own updater verifies, and it is checked automatically. - Launch aiui once from the Start menu.
That's it, on either platform. aiui registers itself with Claude Desktop App automatically. The MCP server ships inside the app itself as native code, so you don't need a Python toolchain on your machine.
From now on aiui runs silently in the background — only while Claude Desktop App is open. No dock icon, no menu-bar clutter, no lingering daemons. aiui tools are available in every Claude Desktop App session immediately; no per-project config needed.
aiui checks for updates every 6 hours in the background and tells you when
one is available — a system notification, and a banner in its settings
window. Installing is one click on that banner, or /aiui:update in Claude
Desktop App. Nothing installs itself without you: aiui restarts to apply an
update, and doing that underneath a dialog you are filling in would be
worse than waiting.
Open any Claude Desktop App session and try one of these — just write it as a normal message:
"Ask me with aiui which of three deploy strategies we want today."
"Confirm with aiui before you delete the test files."
"Use aiui to collect a new user's name, role, and start date."
That's the whole idea. The agent picks the right kind of dialog — yes/no, pick-from-options, or a multi-field form — opens it on your machine, you click, it carries on with your answer.
The first time you do this in a fresh project, run /aiui:teach once.
That briefs the agent on when to reach for aiui versus just typing
back in chat — without it, the agent might forget aiui exists.
| What annoys you today | With aiui |
|---|---|
| Typing answers that are really single clicks | A real native dialog |
| Destructive actions with a vague "please confirm" | Red-styled yes/no, unambiguous |
| Ad-hoc local web UIs for one-off tasks | No longer needed |
| Remote hosts where the agent has no way to ask you | Dialogs tunnel back to your desktop automatically |
| A long task finishes while you've tabbed away | A native OS notification — no dialog, nothing to click |
aiui runs purely locally on your own machine. No telemetry, no usage data: no
dialog content and no answer you give ever leaves your system. A local auth
token lives in the per-user config directory and is only scp'd to hosts you
explicitly register in settings. That directory — ~/.config/aiui/ on macOS
and Linux, %APPDATA%\aiui\ on Windows — also holds the list of registered
hosts (remotes.json) and the first-run flag; uninstall removes all of it,
together with the cached review media.
The one outbound request aiui makes on a spec's behalf is a GET for an
http(s):// image src, fetched on your machine so the dialog can show it —
publicly routable destinations only, never your LAN (see
SECURITY.md). Beyond that and the GitHub-hosted updater feed,
aiui does not phone anywhere.
| Token location | Protection | |
|---|---|---|
| macOS / Linux | ~/.config/aiui/token |
file mode 0600 in a 0700 directory, re-asserted on every launch |
| Windows | %APPDATA%\aiui\token |
the default ACL of your user profile — aiui sets no explicit ACL of its own |
The diagnostic trace lives next to it, in logs/aiui-trace.log under the
same directory (on Windows under %LOCALAPPDATA%\aiui). Its resolved path
is printed in the first line of every log session, so a bug report can name
it precisely.
| Command | What it does |
|---|---|
/aiui:teach |
Briefs the agent on aiui — loads the full widget catalog and design rules into the session. Run once per project. |
/aiui:update |
Agent calls the update tool; aiui checks the release feed, installs any available update, and reports the version delta back. It always answers before the restart, on macOS and on Windows alike. If a dialog is still waiting for you, nothing is installed — you get back "update deferred", because restarting would throw away what you had typed. |
/aiui:version |
Reports the currently installed aiui version in one line. |
/aiui:health |
One-line health check: WebView responsive, no dialog backlog, no child-process flood. |
/aiui:test-dialog |
Pops a tiny demo dialog so you can verify aiui is wired up end to end. |
/aiui:remotes |
Lists your registered remote hosts in chat — the same set the settings window shows. |
/aiui:upload |
Hands a file from your machine to the agent session: a native file picker opens, the file you choose lands on the agent's host. |
Is it safe? aiui is open source (MIT), built only in public GitHub
Actions — never on a maintainer's machine — from third-party actions pinned
to commit SHAs and a Rust compiler pinned in rust-toolchain.toml. The
macOS build is Apple Developer-ID signed and notarized; the Windows
installer carries no Authenticode signature yet (see Install),
but its updater artifacts are signature-verified. It never phones home.
The auth token stays in aiui's config directory on your machine —
~/.config/aiui/ on macOS and Linux, %APPDATA%\aiui\ on Windows — and
is only copied to hosts you explicitly register in settings.
Do I need uv or Python? No. Since v0.3.0 the MCP server ships
inside the aiui.app bundle as native Rust code — drag-and-drop install
with no outside dependencies.
For the special case of a remote SSH host that doesn't have aiui.app
locally, the standalone Python package aiui-mcp is still on PyPI and
gets used via uvx aiui-mcp. aiui registers that automatically when you
add the remote in settings.
A registered remote needs curl 7.55 or newer, which every distribution
shipped since 2017 has. aiui uses it to check, over ssh, whether the port
it wants is already forwarded back to itself. Older curl cannot read a
request header from stdin, and aiui will not pass your API token on a
command line where every other user on that host could read it out of the
process list. On a remote without a usable curl, the check is reported
as inconclusive and the tunnel simply retries — nothing breaks, aiui just
takes longer to notice a stale forward.
How much memory does it use? The companion idles around 30–50 MB. The underlying WebKit view loads only while a dialog is on screen.
Does it work on Intel Macs? No — the macOS build is Apple Silicon (arm64) only. Intel support isn't on the immediate roadmap — open an issue if you need it.
Does it work on Linux or Windows? Windows: yes, since 0.10.1 — x64, with an installer on the release page and in-app updates like on macOS. The installer is not Authenticode-signed, so SmartScreen warns on first launch (see Install). Linux: no, and not planned for now.
Can I use aiui without Claude Desktop? The companion is
auto-spawned by Claude Desktop via its MCP registration, so in the
default setup, no. You can launch aiui.app manually though — as long
as localhost:7777 is reachable, any MCP client can render dialogs.
Why not just use Claude Desktop's built-in AskUserQuestion? It's great for single yes/no or single-choice questions, but doesn't cover multi-field forms, sortable lists, colour pickers, date ranges, or hierarchical pickers. aiui complements it.
Does aiui work in other MCP-capable clients? The aiui-mcp server
is a standard MCP server, so technically yes. The companion is Claude
Desktop-specific in how it auto-installs, but the HTTP protocol on
localhost:7777 is client-agnostic.
What about Codex / ChatGPT? First-class Codex support — where aiui registers itself into Codex's config the same self-contained way it does with Claude Desktop and Claude Code, no manual setup — is in progress. Follow #158 for status.
- macOS: Apple Silicon only (M1 and later), macOS 11 (Big Sur) or later. Intel Macs are not yet supported.
- Windows: x64 only, and the installer is not Authenticode-signed, so SmartScreen warns on first launch. An ARM64 build and a signing certificate are both still open.
- One machine per companion. If you want dialogs on several machines simultaneously, each needs its own aiui install; tokens and tunnels are per-machine.
- Password fields mask input while typing but return the value as plaintext to the agent — see the widget catalog for guidance.
- No headless rendering. aiui needs an active desktop session; it won't render dialogs on a server-style headless install.
| Symptom | What to do |
|---|---|
| No dialog appears | Open aiui (macOS: /Applications/aiui.app; Windows: Start menu) and check the status dot. The remote must show "connected". |
| "aiui companion not reachable" in chat | Claude Desktop isn't running, or your machine is asleep. |
| "Windows protected your PC" when installing | Expected — the installer isn't Authenticode-signed. "More info" → "Run anyway". See Install. |
| "token rejected (401)" | An old aiui process is holding the port on the remote. pkill -f aiui on the remote, then "Remove" and "Add" that remote again in aiui settings. |
| "aiui runs from a temporary location" | You launched aiui from the DMG, ~/Downloads, or a temp folder, so macOS runs it from a copy that won't exist next time. Quit aiui, move aiui.app into Applications, and launch it from there. |
| Status dot red although aiui is running | The aiui entry in your Claude config is stale or incomplete (e.g. missing the --mcp-stdio argument). Click Repair config next to the dot, then restart Claude Desktop. |
Bugs or feature requests → open an issue. The "Report issue" button in settings pre-fills version and build SHA.
aiui is MIT-licensed, hosted at byte5ai/aiui. Pull requests and issues are welcome.
A bit more depth, in roughly increasing nerd-level:
docs/skill.md— the agent-facing widget catalog. aiui installs this as a skill on first launch so Claude knows when to use which dialog and how to write the labels. Worth a skim if you want to understand what aiui can render.CONTRIBUTING.md— repository layout, build flow, release pipeline, design principles.docs/strategy.md— the product thinking behind aiui's V1/V2 split and what we deliberately don't build.aiui-mcpon PyPI — the Python MCP server, used automatically for remote SSH hosts that don't have aiui.app installed locally.