AgentSwitch Manual

Synopsis

ax [pick]                     open the picker
ax new [harness [flags...]]   start a new session
ax "task" [flags]             run a task on your default harness
ax <harness> "task" [flags]   run a task on a named harness
ax read | send | tag | ask | reply | runs | kill | list
ax help

ax "task" is the short form once you set default_harness (see Configuration file). A known verb or harness name shadows a bare prompt, so ax <harness> "task" still targets a specific harness. Both forms appear below.

Description

AgentSwitch is a daemonless switchboard for CLI coding agents. It ships as a single Go binary called ax that launches, watches, detaches, reattaches, and coordinates agent sessions from one TUI. Each coding agent (a harness) already writes its own transcripts. ax reads those stores, lists every session in one searchable terminal picker, and resumes the one you pick by running that harness's own resume command.

ax does not replace your harness, and it has no LLM of its own. There is no daemon either: everything works off local files, databases, and the heartbeat files live sessions write. No mux is the default, and it is first-class, not a fallback. Out of the box, with zero external dependencies, ax's own session holder keeps your harnesses alive when you detach (Ctrl-a then d), and the picker lets you check on them across projects and reattach. The full launch, detach, monitor, reattach loop works with no tmux or zellij installed.

A multiplexer is optional, never required. When you run tmux or zellij, ax drives it natively, opening and managing panes and windows for your sessions. If a session is already open, ax jumps to its window instead of starting a second copy. Sessions on other machines fold into the same list over SSH (see Remote hosts).

ax also has a set of shell verbs, so one session can drive others: launch sessions, read their turns, steer them, gate their completion on an accept check, and stop them. Hard limits on cost, fan-out, and time bound every run (see Control plane). Run the verbs yourself, or hand a session a short behavior prompt that names the commands, and it becomes the coordinator.

ax builds on tools native to your system (tmux, dtach, ssh) rather than a runtime of its own, so every backend piece is swappable. Extending it takes one [[harness]] block, and that block is the whole interface. One picker and one verb set cover local LLMs, frontier-model harnesses, and remote sessions.

For step-by-step walkthroughs with real captured terminal output, see the tutorials page.

Installation

Install Methods

Runtime Requirements

Fuzzy matching is built in, so you don't need fzf. Everything below is optional and degrades gracefully when it is missing. If you already use one, ax picks it up on its own.

For a remote host, ax and dtach must be installed on that host too.

By default ax runs on its own session holder with no multiplexer. That is first-class, not a fallback: sessions launch, stay alive when you detach (Ctrl-a then d), show up in the picker, and reattach on demand. Set a multiplexer and ax drives it natively, so live sessions run as real windows or tabs you can jump into. One config setting picks the backend.

Pick a backend with the mux setting in your config file:

# ~/.config/ax/config.toml
mux = "tmux"     # optional. unset uses the built-in no-mux holder. tmux, zellij, process, or none

An unset or unrecognized value means the built-in no-mux holder (the same behavior as process), so ax works with no config at all and no multiplexer installed. Set mux to tmux or zellij to have ax drive that multiplexer instead. Under none ax launches the session in the current terminal and does not track it.

The tmux and zellij backends prefix every window, session, and tab name they create with ax:, so ax-managed windows stand out in the native status bar and a single prefix match selects all of them. Set mux_prefix to use a different prefix, or mux_prefix = "off" to disable it. The process and none backends have nothing to name, so the prefix does not apply to them.

Layout

Each harness tells ax where its transcripts live, how to pull a session id out of them, which parser to use, and how to launch or resume a session. ax scans those stores and builds one table: status, model, age, context use, cost, directory, window, and title for every session, local or remote.

Sessions ax launches write heartbeat files while they run. From those files, tmux window metadata, and a harness state hook if you install one, the picker knows whether a session is working, idle, blocked on you, done and waiting for review, or dead after a bad exit.

Example Screen

The picker is a terminal table with a transcript preview pane below it. The example uses the default columns and sample data.

Status Values

The STATUS column folds attention, activity, and liveness into one cell. When several apply, the most pressing wins: attention first, then activity, then a crash. Blank means the session is not running.

Columns

A few columns show up on their own: HOST when you have remote hosts, NAME and GROUP when there are runs, and TAGS once anything is tagged. Put tag:<key> in the columns config to pin one tag key as its own column.

Keys

The picker opens in normal mode. You can rebind any key below under [keys] in the config. The help screen (?) and the hint row always show the keys you have set. Enter (open), Esc (leave a mode), and the arrow keys are fixed.

Commands

Model

A session is a job. One session can drive others: launch them, read what they produce, steer them, decide when they are done, and stop them once a check passes, with little or no human in the loop. ax itself is only the mechanism. It has no LLM and never judges whether a task is finished. It reports facts (a turn finished, a session is waiting, a session exited or crashed), performs actions (launch, read, send, tag, ask, kill), and enforces limits. The thinking always happens in a session.

There is no daemon. The verbs are stateless CLI commands that read and write sidecar files. The only long-running piece is the coordinator, and that is itself a session ax manages.

The Launcher

A task launch (ax "task", or ax <harness> "task" for a specific harness) launches without a prompt and prints the session id and run id, so a script or a coordinator can grab them:

$ ax "fix the flaky test"
a1b2c3d4  a1b2

$ ax "add a CHANGELOG entry" --wait --unattended
$ echo $?
0

$ ax "build a blog" --behavior ~/.config/ax/coordinator.md --max-cost 100 \
    --max-depth 2 --accept ./verify.sh

By default a task runs watched: the harness runs interactively in a tracked window and the session concludes into a done state when the task finishes, so you can watch it, ax send to it, and read its final report after. It skips the folder-trust prompt, so a session started in a fresh directory (a worktree, a /tmp dir) never hangs waiting on it. --close-on-done ends the window when the task finishes instead of holding it in done. --headless (or --wait) opts into a headless job that runs the harness non-interactively (for Claude Code, claude -p) and exits on done.

--wait blocks and hands back an exit code: 0 when the session tagged success (and --accept passed), non-zero on a fence trip, a give-up, or a crash. Idle never counts as done. --unattended makes ax ask return a default instead of blocking, so a CI run can't deadlock waiting on a human. The one-line CI shape:

ax "make 'go vet ./...' pass" --wait --unattended --accept "go vet ./..." --timeout 30m

Verbs

Every verb is non-interactive: ids and data on stdout, diagnostics on stderr, and exit codes that reflect the outcome. Any verb that takes an id also takes a host/id, and routes over that host's transport.

read --follow emits turn, waiting (reason input or auth), exit, and crash events, one JSON object per line, each carrying a cursor and a short preview.

Fences, Accept Check, Ask / Reply

Fences are hard limits ax enforces, the LLM-workload version of pod resource limits. Depth and session fences are checked at launch. Cost, token, and time fences are polled by the run's root session, which cascade-kills the run and writes the run record the moment one trips.

The accept check is --accept ./check.sh. When a session tags --outcome success, ax runs the script. A non-zero exit rejects the tag and feeds the output back, so a run cannot conclude on an unverified claim. For ask / reply (ax ask / ax reply), the behavior decides when to ask a human. ax blocks the session, sends the notification, and holds the question until you answer.

Launch from inside a session and it inherits that session's run and parent automatically (through AX_SESSION_ID, AX_RUN, AX_DEPTH, and the fence limits ax puts in the environment), so the run tree assembles automatically. --group and AX_GROUP still work as deprecated aliases for --run and AX_RUN. A [policy] section can also allow-list harnesses and allow or deny models at launch.

The Coordinator

A coordinator is a session launched with a coordinator behavior prompt. That prompt is a recipe file, not something baked into the binary, so --behavior takes the path to it. Copy recipes/coordinator.md to a stable location once (the quick start does this) and point --behavior at that path. The coordinator splits the work, launches sessions, judges their results against the evidence, and concludes when the criteria pass. ax imposes no shape on the run: pipeline, fan-out, tournament, and recursion are all decided by the session.

--behavior takes the path to a behavior file (or a literal string). Copy behaviors/coordinator.md to ~/.config/ax/coordinator.md and pass that path.

ax "Add dark mode to this app. Done when: the toggle works and 'npm test' passes." \
    --behavior ~/.config/ax/coordinator.md --model opus --max-cost 25 --max-workers 3

Watch the run in the picker: f filters to the run, T shows the run tree.

 ax v0.1.0  NORMAL ───────────── run:blog-x1  tree ── 4 sessions · $19 · 4 live  ? help

 HARNESS  STATUS      NAME           GROUP    MODEL       AGE  CTX  COST   TITLE
 claude   ⠧ working   coordinator    blog-x1  opus-4-8    now  38%  $9.80  build a blog about racecars
 claude   ⠋ working   ├─ posts       blog-x1  sonnet-4-6  now  22%  $5.14  write the first six posts
 claude   needs you   ├─ theme       blog-x1  sonnet-4-6  1m   17%  $3.02  dark retro theme
 codex    idle        └─ deploy      blog-x1  gpt-5.5     3m   9%   $1.21  wire the pages deploy

Attention rolls up the tree: the root session shows needs you whenever any session under it is blocked, so you go straight to the blocked session instead of scanning. Answer with r.

Done and Review

An attended run does not stop silently. When the session's criteria pass, it tags --outcome success (and runs the --accept check if you set one), shows a one-line result through ax ask, and waits. The picker marks this the green ✓ review state, separate from the red needs you: the run is presenting its result, not blocked. Reply to accept it, or reply with new criteria and it keeps going. Finished runs land in ax runs with an outcome of success, gave_up, budget_hit, or crashed.

Federation

ax merges sessions from other machines into one list over SSH, or any transport command:

# ~/.config/ax/config.toml
[[host]]
name      = "laptop"
transport = "ssh -t user@laptop"

Each host needs ax installed (and dtach, so its sessions survive). No daemon, no open port: ax runs the transport command, and that command carries its own auth. Pick a remote session and it attaches over the transport in a local window. ax kill, ax read, and the rest route the same way. c can start a new session on a host, and m filters the list by machine and shows each host's status: online, offline, no ax, or old ax.

Containers work the same way: a transport like container exec -i <id> or kubectl exec makes a container or a pod another host, and throwaway boxes can register themselves into the picker. Setup details, advice on credentials, and the reasoning behind sandboxing are in the GitHub README and docs/control-layer.md.

Disposable Boxes

An unattended agent will do whatever it decides the task needs, and it can be steered by anything it reads. So don't run it on your workstation. Give it a dedicated, disposable box, one clone or worktree per task, and tear it down when the task is done. A box that only ever held one job holds nothing valuable to steal and nothing important to break.

Keep trust one-directional. Your machine reaches into the agent box. The box does not reach back. ax fits this shape by design: it pulls over your transport, runs no daemon, and opens no port. Nothing on the box waits for a connection, so the agent has no path back to your machine.

Never forward your SSH agent into an agent box. An injected prompt that lands on a box with a forwarded agent can authenticate as you to every host your key reaches, and ssh -A (or a careless ProxyJump) grants exactly that. The default ssh -t transport does not forward the agent.

Secrets and Egress

Keep no standing secrets on the box. No personal SSH keys, no cloud credentials, no password manager. Inject short-lived, task-scoped credentials for the one job at hand, so a compromised box leaks a narrow, expiring grant instead of your long-lived credentials.

Default-deny egress. An agent that can reach the whole internet can exfiltrate anything it touches and pull in anything it is told to. Allowlist only what the task needs: the LLM API, the package registries it builds against, and the git remotes it pushes to. Everything else stays blocked.

Configuration File

Claude Code, Codex, pi, and opencode are built in and work with no config file at all. To change one of them or add your own harness, copy config.example.toml to ~/.config/ax/config.toml. Overrides happen field by field: a [[harness]] with just name and args adds flags but keeps the built-in glob, resume, and launch. Point AX_CONFIG at another file to use it instead. When XDG_CONFIG_HOME is set, the default path is $XDG_CONFIG_HOME/ax/config.toml.

# ~/.config/ax/config.toml

default_harness = "claude"

columns = ["harness", "status", "model", "age", "ctx", "cost", "dir", "win", "title"]

[[harness]]
name = "myagent"
glob = "~/.myagent/sessions/*/*.jsonl"
id_regex = "_(?P<id>[0-9a-f-]{36})\\.jsonl$"
format = "pi"
resume = "cd {dir} && myagent --resume {id} {args}"
launch = "myagent {args}"
args = "--profile work"

[keys]
kill = "K"

[[host]]
name      = "laptop"
transport = "ssh -t user@laptop"

Harness Fields

Other Sections

Supported Harnesses

Model Data

Context sizes and prices come from models.dev. A snapshot ships inside the binary so it works offline. ax models update writes a fresh copy to the state directory, and that copy wins at runtime.

Treat the cost columns as a guide, not a bill. When a harness records its own cost, ax shows that. Otherwise it estimates from the transcript's token counts and models.dev pricing. It won't always match what you are billed under subscriptions, bundled usage, credits, or provider-specific pricing.

Local State

State files live under ~/.local/state/ax/, or $XDG_STATE_HOME/ax/ when it is set. ax never touches your transcripts. Everything it adds is sidecar data.

Copy-Paste Playbooks

Every recipe runs as written. Edit the quoted task text to match your job. No configuration is needed first. Example:

ax "run go test ./... and fix any failures"

All the playbooks are on the recipes page: run a task, run an accept check in CI, organize sessions with tags, watch a run from a shell, get notified when a run needs you, coordinate a goal with multiple agents, run an ongoing project with a coordinator, supervise an existing session, and change the goalposts mid-run. The source they come from is docs/recipes.md.