Skip to content

Agent Usage

aimux supports structured output for consumption by AI coding agents (Claude Code, Codex) and scripts.

Call once per session to learn the full CLI contract:

Terminal window
aimux agent-context

Returns every command, flag, type, default, and valid enum as JSON. Agents use this to avoid guessing flag names or values.

Add --json for machine-parseable JSON output:

Terminal window
aimux agents --json
aimux sessions --list --json
aimux version --json
aimux spawn claude --dry-run --json
aimux resume <id> --dry-run --json
aimux jump <id> --json
aimux profile list --json
aimux feedback "message" --json

Exceptions: 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.

CodeMeaning
0Success
1General error
2Usage error (bad flags, missing args)
3Not found (no sessions, no agents)
4Config 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.

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.

Use --fields to select specific output columns:

Terminal window
aimux sessions --list --json --fields id,project,cost
aimux agents --json --fields pid,provider,status

Session 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).

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"}

Preview commands before executing:

Terminal window
aimux spawn claude --dir ./myproject --dry-run --json
aimux resume <id> --dry-run --json

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:

Terminal window
aimux profile save work --provider claude --model opus --dir ~/project
aimux spawn --profile work
aimux profile get work --json
aimux profile delete work

Explicit flags override profile values.

Route spawn output to different sinks:

Terminal window
aimux spawn claude --json --deliver=file:./result.json
aimux spawn claude --json --deliver=webhook:https://hooks.example.com/agents

Valid schemes: stdout (default), file:<path>, webhook:<url>.

Block until a spawned agent session finishes:

Terminal window
aimux spawn claude --dir ./project --wait --json

Returns duration on completion. Eliminates the need for agents to write polling loops.

Report CLI friction for maintainer review:

Terminal window
aimux feedback "the --limit flag silently ignores values over 100"

Writes to ~/.aimux/feedback.jsonl.

Errors include valid values when applicable:

Terminal window
$ aimux spawn gpt
Error: 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"]}

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_sessions prints 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 is idle or open_in_terminal; open_in_terminal means 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 as unknown · 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 with include_automated, except sessions started from the phone. days, project_filter and limit apply after that; limit 0 or below means 200. A session with no recorded activity time uses its transcript’s modified time.
  • get_session still 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.

Add to ~/.aimux/config.yaml:

resume:
skip_permissions: true # pass --dangerously-skip-permissions with `aimux resume` (the web dashboard asks per resume)