name	agent-ui
description	Shows native macOS UI dialogs for CLI agents — notifications, confirmations, text input, choices, file pickers, forms, progress bars, diffs, images, tables, toasts, wizards, ratings, date pickers, checklists, search, logs, and secret input. Use when a script or agent needs to interact with a human operator through desktop UI rather than terminal prompts.

Agent-UI

Native macOS desktop UI primitives for CLI agents. All commands output JSON to stdout and use exit codes for status.

Quick start

agent-ui notify --title "Done" --body-md "Build passed."
agent-ui confirm --title "Deploy?" --body-md "Push to production?"
agent-ui input --title "Name" --placeholder "Enter your name"
agent-ui choose --title "Env" -o "dev:Development" -o "prod:Production"
agent-ui pick --files --title "Select config"
agent-ui show --title "Results" --body-md "# Summary\n\n42 files processed"

Which command do I use?

Need to ask the user a question or collect text?

confirm — simple yes/no approval gate
input — free-text entry (single-line or multiline)
secret — masked password/token input
form — collect multiple fields at once (text, number, select, toggle, textarea)
wizard — multi-step guided flow with back/next navigation

See input-commands.md for flags and examples.

Need the user to pick from options?

choose — select from a short list of options
search — fuzzy-searchable list for large option sets
pick — native macOS file/folder picker
date — date, time, or datetime picker
checklist — approve/select multiple items from a list
rating — star rating (1-5) or thumbs up/down feedback

See selection-commands.md for flags and examples.

Need to show the user information?

notify — native macOS notification banner (fire-and-forget)
toast — transient in-app notification that auto-fades
show — markdown content panel with optional action buttons
progress — determinate or indeterminate progress bar (updateable)
diff — side-by-side or unified diff viewer with approve/reject
image — display a local or remote image
table — sortable, scrollable data table
log — streaming monospace log viewer (reads stdin)

See display-commands.md for flags and examples.

Need multi-step or updateable flows?

--interaction-id — create a dialog you can update in place
--session-id — chain commands in a single window
close / wait — programmatic control of sessions and interactions

See stateful.md for patterns and examples.

Response format

Every command returns JSON:

{"id": "", "status": "ok", "action": "submit", "value": "user input", "ts": 1738857600000}

Exit code	Status	Meaning
0	ok	Action completed
10	cancelled	User cancelled
11	timeout	Timed out
20	error	Invalid arguments
30	error	UI unavailable

Common flags

All commands accept: --title, --body-md, --body-md-file, --id, --timeout, --json

Stateful flags (auto-starts daemon): --session-id, --interaction-id, --closeable

Button format (for notify and show): id:Label:style:alignment[:close]

style: primary, secondary, destructive
alignment: left, right
:close (show only): closes session on click

name	agent-ui
description	Shows native macOS UI dialogs for CLI agents — notifications, confirmations, text input, choices, file pickers, forms, progress bars, diffs, images, tables, toasts, wizards, ratings, date pickers, checklists, search, logs, and secret input. Use when a script or agent needs to interact with a human operator through desktop UI rather than terminal prompts.