AgentSwitch Tutorials

Your First ax Session

Setup

Install ax (see Installation). There is no configuration step: Claude Code, Codex, pi, and opencode are built in, and ax reads the transcript stores those harnesses already write.

No mux is the default. Out of the box, with nothing else installed, ax's own session holder keeps your harnesses alive when you detach (Ctrl-a then d) and lists them in the picker, so the full launch, detach, monitor, reattach loop works on a plain terminal. A multiplexer is optional: if you run tmux (or zellij), ax drives it natively and opens each session as a real window. dtach, zoxide, and ripgrep are picked up on their own too. See the manual's runtime requirements for what each one adds. None is required.

See What You Already Have

ax indexes the sessions that exist on your machine right now. Before opening any UI, list them:

ax list output: four sessions across claude and codex, one live and working in ~/src/webshop, with model, age, context, cost, directory, and title columns

Four sessions across two harnesses. One is live and working: a claude run in ~/src/webshop that was launched through ax. The others are past conversations you can resume.

Open the Picker

ax opens the picker: the same table, plus a live preview of the selected session's transcript.

the ax picker: a session table with harness, status, model, age, context, cost, directory, and title columns, a key hint row, and a transcript preview of the selected webshop session below

Move with j/k. The preview follows the cursor. J/K scroll the preview itself. The STATUS column merges liveness and attention into one cell. The manual's status table lists every value.

Find a Session

There are two search prompts with different scopes. i filters rows on their metadata (harness, directory, title). / searches inside the transcripts themselves:

the picker in search mode: the query 'rounding' typed at the search prompt has narrowed the list to the one session whose transcript mentions it, with the matching lines shown in the preview

Typing rounding narrowed the list to the one session whose conversation mentions it, with the match shown in the preview. n/N jump between matches. Esc backs out, Enter keeps the narrowed list so you can act on it.

Resume, or Start Fresh

Enter on a row resumes that session with the harness's own resume command, in the session's directory. If it is already open somewhere, ax jumps to it instead of starting a duplicate. x kills a session.

c (or ax new) starts a fresh session: pick a harness, pick a directory, and it launches. From the shell, ax new claude skips the picker entirely.

The list is not limited to this machine or these harnesses: a [[harness]] entry can point at a local LLM's CLI or a frontier-model harness, and remote hosts merge their sessions into the same picker. The next tutorial drives sessions from the shell instead.

Running a Coordinated Task

Launch

A coordinated run is one command. The task states the goal and the done-criteria. The flags cap cost, tokens, workers, depth, and wall-clock time:

ax prints the new session id and the run's group id and returns. The root session (the coordinator) now splits the work and launches sessions through ax. Each launch inherits the group, so the run tree assembles automatically. --max-cost 25 and --max-workers 3 are enforced by ax, not by the model: a launch beyond the session cap is refused, and a cost overrun cascade-kills the run.

The coordinator is an ordinary session handed a behavior prompt that names the ax verbs. Every action it takes from here (launch, read, send, tag, ask) is a plain shell command you could type yourself.

Watch the Run

The group id addresses the whole run from the shell:

ax list --group b3e7a9c2: the coordinator and three named sessions (toggle-ui, theme-css, tests) with their status, model, cost, and task, where theme-css shows needs you

In the picker, f filters to the group and T renders the parent tree, like a process viewer:

the picker in run-tree mode filtered to group b3e7a9c2: the coordinator at the root with three indented sessions, theme-css marked red 'needs you', and its pending question shown in the preview pane

One session is red: theme-css hit a decision it would not make alone, called ax ask, and blocked. The question appears in the preview.

Answer It

Press r on the row and type the answer, or from any shell:

ax reply with the session id and the answer text 'the high-contrast near-black'

The blocked ax ask call inside the session returns your text on its stdout and the session continues. The reply is free-form: it can be a choice, a correction, or the next instruction. This was the run's only human intervention, and it happened because the behavior chose to ask.

You can also read any session's conversation without attaching to it, as normalized turns from the transcript:

ax read of the tests session with --limit 2: a JSON object with the session id, two normalized turns with role, timestamp, text, and token counts, and a cursor

ax read --group b3e7a9c2 --follow gives you the same thing as a stream. It blocks and emits one JSON line per turn boundary across the whole run. A coordinator runs on this same stream.

Review and Accept

When the criteria pass, the run does not stop silently. The root tags --outcome success, presents a one-line result via ax ask, and waits. In the picker that is the green ✓ review state, ranked with the attention states but distinct from red needs you: the run is presenting its result, not blocked.

the picker after the run concluded: the coordinator row shows a green '✓ review' status, and the preview shows outcome success with the question 'result ready: the toggle works, choice persists, npm test passes 42/42. accept?'

Reply to accept, or reply with updated criteria and the run continues. With --accept ./check.sh on the launch, the success tag additionally has to pass your script, so a run can never conclude on an unverified claim.

Concluded runs are recorded and can be queried:

ax runs output: one concluded run record for group b3e7a9c2 with outcome success, cost $18.42, three sessions, depth 1, and the task text

Where to Go Next

The manual's Control plane chapter covers the full verb set, the fences, and the accept check. The recipes page has copy-paste playbooks, including running an accept check in CI with --wait --unattended, supervising an already-running session toward a goal, and getting notified when a run needs you.