---
title: Agent Usage
description: Using aimux from AI coding agents and scripts
---

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

## Introspection

Call once per session to learn the full CLI contract:

```bash
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:

```bash
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:

```bash
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:

```json
{"sessions": [...], "count": 10, "total": 142, "truncated": true, "hint": "use --limit to control result count"}
```

## Dry Run

Preview commands before executing:

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

## Profiles

Save named configuration bundles for reuse:

```bash
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:

```bash
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:

```bash
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:

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

Writes to `~/.aimux/feedback.jsonl`.

## Error Messages

Errors include valid values when applicable:

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

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

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

## Configuration

Add to `~/.aimux/config.yaml`:

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