https://github.com/byte5ai/aiui
Native macOS dialogs for Claude Code — ask, confirm, collect input where you actually work.
https://github.com/byte5ai/aiui
ai-agents anthropic claude claude-code developer-tools dialog macos mcp rust svelte tauri ui
Last synced: 23 days ago
JSON representation
Native macOS dialogs for Claude Code — ask, confirm, collect input where you actually work.
- Host: GitHub
- URL: https://github.com/byte5ai/aiui
- Owner: byte5ai
- License: mit
- Created: 2026-04-23T11:12:48.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-30T15:12:09.000Z (23 days ago)
- Last Synced: 2026-05-30T16:16:05.651Z (23 days ago)
- Topics: ai-agents, anthropic, claude, claude-code, developer-tools, dialog, macos, mcp, rust, svelte, tauri, ui
- Language: Rust
- Homepage: https://github.com/byte5ai/aiui/releases/latest
- Size: 15.7 MB
- Stars: 3
- Watchers: 0
- Forks: 1
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# aiui
**Claude Desktop App can ask, confirm, and collect input — as real native macOS dialogs.**
[](https://github.com/byte5ai/aiui/releases/latest)
[](https://github.com/byte5ai/aiui/blob/main/LICENSE)
---
## The chat is sometimes the wrong place
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 Mac:
- **"Which of these three deploy strategies?"** A window with three
cards, each with context. One click. Done.
- **"Shall I drop the production `orders` table?"** 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 macOS window that does what it looks like.
## Works locally and remotely
Running Claude Desktop App directly on your Mac? 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 Mac. Register the host once in settings; from then on it just
works.
## Install
No Terminal. No Homebrew. No Python. No `uv`.
1. **[Download aiui.app](https://github.com/byte5ai/aiui/releases/latest)**
(DMG, Apple Silicon).
2. Drag into `Applications`.
3. Launch it once from Finder.
That's it. aiui registers itself with Claude Desktop App
automatically. The MCP server ships inside the app bundle as native
code, so you don't need a Python toolchain on your Mac.
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.
Updates install themselves in the background. If you want to force a
check, use `/aiui:update` in Claude Desktop App, or open aiui's settings
window.
## Quickstart
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
Mac, 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 you get
| What annoys you today | With aiui |
|---|---|
| Typing answers that are really single clicks | A real macOS 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 Mac automatically |
## Privacy
aiui runs purely locally on your Mac. No telemetry, no usage data, no
content leaves your system. A local auth token lives in `~/.config/aiui/`
(mode 0600) and is only scp'd to hosts you explicitly register in
settings.
## Slash commands in Claude Desktop App
| 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, silently installs any available update, and reports the version delta back. Responds before the background relaunch, so the agent always gets the answer. |
| `/aiui:version` | Reports the currently installed aiui version in one line. |
## FAQ
**Is it safe?** aiui is open source (MIT), builds reproducibly, is Apple
Developer-ID signed and notarized. It never phones home. The auth token
stays under `~/.config/aiui/` on your machine 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.
**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?** Currently Apple Silicon (arm64) only.
Intel support isn't on the immediate roadmap — [open an issue](https://github.com/byte5ai/aiui/issues/new)
if you need it.
**Does it work on Linux or Windows?** Linux: no. Windows: in progress —
the Rust core and CI build already target Windows; interactive E2E testing
and a first release are still outstanding. Follow
[#118](https://github.com/byte5ai/aiui/pull/118) for status.
**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.
## Known limitations
- **Apple Silicon only** (M1 and later). Intel Macs are not yet
supported.
- **macOS 11 (Big Sur) or later.**
- **One Mac per companion.** If you want dialogs on multiple Macs
simultaneously, each needs its own aiui install; tokens and tunnels
are per-Mac.
- **Password fields** mask input while typing but return the value as
plaintext to the agent — see the [widget catalog](docs/skill.md#password-fields)
for guidance.
- **No headless rendering.** aiui needs an active macOS GUI session;
it won't render dialogs on a server-style headless install.
## Troubleshooting
| Symptom | What to do |
|---|---|
| No dialog appears | Open `/Applications/aiui.app` and check the status dot. The remote must show "connected". |
| "aiui companion not reachable" in chat | Claude Desktop isn't running, or the Mac is asleep. |
| "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. |
Bugs or feature requests → [open an issue](https://github.com/byte5ai/aiui/issues/new).
The "Report issue" button in settings pre-fills version and build SHA.
## Open source
aiui is MIT-licensed, hosted at [byte5ai/aiui](https://github.com/byte5ai/aiui).
Pull requests and issues are welcome.
## For developers & curious users
A bit more depth, in roughly increasing nerd-level:
- [`docs/skill.md`](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`](CONTRIBUTING.md) — repository layout, build flow,
release pipeline, design principles.
- [`docs/strategy.md`](docs/strategy.md) — the product thinking behind
aiui's V1/V2 split and what we deliberately don't build.
- [`aiui-mcp`](https://pypi.org/project/aiui-mcp/) on PyPI — the Python
MCP server, used automatically for remote SSH hosts that don't have
aiui.app installed locally.