Agent Usage
aimux supports structured output for consumption by AI coding agents (Claude Code, Codex) and scripts.
Introspection
Section titled “Introspection”Call once per session to learn the full CLI contract:
aimux agent-contextReturns every command, flag, type, default, and valid enum as JSON. Agents use this to avoid guessing flag names or values.
Structured Output
Section titled “Structured Output”Add --json for machine-parseable JSON output:
aimux agents --jsonaimux sessions --list --jsonaimux version --jsonaimux spawn claude --dry-run --jsonaimux resume <id> --dry-run --jsonaimux jump <id> --jsonaimux profile list --jsonaimux feedback "message" --jsonExceptions: aimux chat --json prints one JSON event per line (JSON Lines) as the reply streams. aimux mcp proxy status --json prints the proxy’s status object. The other MCP proxy commands (mcp proxy refresh, serve, config) and remote serve print text: a per-server report, a startup line, or setup instructions. aimux browser install, setup, verify and host print text even with --json: install and setup print what they wrote, verify prints one line per check. The v2 nouns print one JSON document with schema_version under --json: aimux tools status|diff|approve|add|remove, aimux sandbox status, aimux router status|test, aimux setup and aimux doctor. Their notes and Next: hints go to stderr, so stdout stays parseable.
Exit Codes
Section titled “Exit Codes”| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Usage error (bad flags, missing args) |
| 3 | Not found (no sessions, no agents) |
| 4 | Config error |
aimux chat, aimux jump, aimux remote serve, aimux mcp proxy, aimux browser and the v2 aimux profile commands (list, show, check, migrate) return 1 for every failure, including missing arguments, an unknown session or profile and a bad setting. aimux profile check also returns 1 when a profile widens its parent, has an invalid sandbox name, or names a role whose profile does not check (including a planner that is not a sandbox profile without web, or a writer that is not an acp profile without tools or web, even when that profile checks on its own); aimux profile list shows a profile that does not resolve with digest -, prints the reason on stderr and still exits 0. The same holds for aimux tools, aimux sandbox, aimux router, aimux setup and aimux doctor (usage errors return 1, not 2). Status commands (tools status, sandbox status, router status) exit 0 even when something needs attention and say so on stderr; aimux doctor exits 1 only when a check fails (warnings exit 0); aimux tools approve exits 1 when it skipped a tool; aimux router test exits 1 on an invalid router config.
Non-Interactive Mode
Section titled “Non-Interactive Mode”When stdin is not a TTY (piped or called by an agent), aimux sessions automatically behaves as aimux sessions --list instead of launching the interactive picker.
Field Selection
Section titled “Field Selection”Use --fields to select specific output columns:
aimux sessions --list --json --fields id,project,costaimux agents --json --fields pid,provider,statusSession fields worth knowing: title (the .meta.json title, if any), title_by (owner when you wrote it, otherwise aimux generated it), custom_title (the name given with Claude Code’s /rename), ai_title (the name Claude Code gave the session), first_prompt (the first prompt), last_prompt (the last message the person typed: not tool results, hook feedback, notifications, messages from other sessions or image placeholders), project (rebuilt from Claude’s folder name) and cwd (the working directory recorded in the session, exact where project can be ambiguous).
Bounded Output
Section titled “Bounded Output”Use --limit to control result count. When results are truncated, JSON output includes a hint:
{"sessions": [...], "count": 10, "total": 142, "truncated": true, "hint": "use --limit to control result count"}Dry Run
Section titled “Dry Run”Preview commands before executing:
aimux spawn claude --dir ./myproject --dry-run --jsonaimux resume <id> --dry-run --jsonProfiles
Section titled “Profiles”Save named configuration bundles for reuse. These are v1 profiles; aimux profile list --json now lists the v2 profiles, and aimux profile migrate converts the saved ones:
aimux profile save work --provider claude --model opus --dir ~/projectaimux spawn --profile workaimux profile get work --jsonaimux profile delete workExplicit flags override profile values.
Delivery Targets
Section titled “Delivery Targets”Route spawn output to different sinks:
aimux spawn claude --json --deliver=file:./result.jsonaimux spawn claude --json --deliver=webhook:https://hooks.example.com/agentsValid schemes: stdout (default), file:<path>, webhook:<url>.
Waiting for Completion
Section titled “Waiting for Completion”Block until a spawned agent session finishes:
aimux spawn claude --dir ./project --wait --jsonReturns duration on completion. Eliminates the need for agents to write polling loops.
Feedback
Section titled “Feedback”Report CLI friction for maintainer review:
aimux feedback "the --limit flag silently ignores values over 100"Writes to ~/.aimux/feedback.jsonl.
Error Messages
Section titled “Error Messages”Errors include valid values when applicable:
$ aimux spawn gptError: invalid provider "gpt" (must be one of: claude, codex)With --json, errors go to stderr as structured JSON (except aimux chat, whose --json covers the event stream; its errors stay plain text):
{"error": "invalid provider \"gpt\"", "code": 2, "valid_values": ["claude", "codex"]}Session Search over MCP
Section titled “Session Search over MCP”aimux mcp serve exposes session search, transcript reading and resume as MCP tools over stdio. It shares the ranked index with aimux sessions (~/.aimux/search.db). Each tool call picks up changed session files and embeds them in the background, so calls don’t wait for them; only a new query’s own embedding calls the API (cached after the first time). New content matches by keyword at once and usually joins semantic ranking within seconds. If more than 20 sessions changed at once, they are not embedded automatically; run aimux sessions index to catch up. If the embedding API is unreachable, the work stays queued and the next tool call retries it, even if no files changed. One-shot CLI searches (aimux sessions "query" --list) embed inline instead, since the process exits right after answering. One exception: when the index was written by a newer aimux build (several builds can share the file, one per open session), an older build uses it as it is without refreshing and logs a note once, and aimux sessions index refuses to rebuild it; update aimux to bring that build’s search up to date.
list_sessions and get_session use the session catalog, the same one the phone clients see:
list_sessionsprints one line per session, newest first:- `<id>` <last active> · **<title>** · <directory> · <provider> · <state>. The title follows the one title rule (your title,/rename, aimux’s generated title, Claude Code’s name, then the first message). The state isidleoropen_in_terminal;open_in_terminalmeans a process holds the session, which is usually a terminal but can also be aimux’s own remote adapter while the phone runs a turn. Sessions whose transcript only aimux’s archive still has (~/.aimux/archive) come from the search index asunknown · archived, under the same visibility rule; if the index cannot be read, the list says so and shows the rest, and if finding them takes more than 20 pages of 100 index rows, it stops and says older ones may be missing. Subagents never show. Automated sessions and aimux’s own analyzer sessions show only withinclude_automated, except sessions started from the phone.days,project_filterandlimitapply after that;limit0 or below means 200. A session with no recorded activity time uses its transcript’s modified time.get_sessionstill reads the transcript through the search index. For a session the catalog knows, it shows the same title in full and adds**Provider:**and**State:**lines to its header; an archive-only session keeps the index’s title and has neither line.
search_sessions, continue_session and create_virtual_session read the search index as before.
Configuration
Section titled “Configuration”Add to ~/.aimux/config.yaml:
resume: skip_permissions: true # pass --dangerously-skip-permissions with `aimux resume` (the web dashboard asks per resume)