Agent Usage

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

Introspection

Call once per session to learn the full CLI contract:

aimux agent-context

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

Structured Output

Add --json to any command for machine-parseable JSON output:

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

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

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

Use --fields to select specific output columns:

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

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

Preview commands before executing:

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

Profiles

Save named configuration bundles for reuse:

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

Explicit flags override profile values.

Delivery Targets

Route spawn output to different sinks:

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

Waiting for Completion

Block until a spawned agent session finishes:

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

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

Feedback

Report CLI friction for maintainer review:

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

Writes to ~/.aimux/feedback.jsonl.

Error Messages

Errors include valid values when applicable:

$ aimux spawn gpt
Error: invalid provider "gpt" (must be one of: claude, codex)

With --json, errors go to stderr as structured JSON:

{"error": "invalid provider \"gpt\"", "code": 2, "valid_values": ["claude", "codex"]}

Configuration

Add to ~/.aimux/config.yaml:

resume:
  skip_permissions: true    # always pass --dangerously-skip-permissions on resume