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. 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 launch, detach, monitor, reattach loop works with no tmux or zellij installed.

A multiplexer is optional. 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 give a session a short behavior prompt that names the commands, and it can coordinate the run.

ax builds on tools native to your system (tmux, ConPTY, SSH, local files) rather than a runtime of its own, so every backend piece is swappable. Extending it takes one [[harness]] block. 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. ax keeps working when these tools are missing. If you already use one, ax can use it.

For a remote host, ax must be installed on that host too. Install dtach there only if that host explicitly uses the dtach hold backend.

By default ax runs on its own session holder with no multiplexer. 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 judgment 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 \
    --write './.coordinator/**/*.md' --no-subagents --max-depth 2 \
    --label role=coordinator --max-cost 100 --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 is the explicit opt-in to a screenless 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. A waited task still runs watched under the holder unless you also pass --headless, so it remains attachable while the caller waits. --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.

ax read --run "$AX_RUN" --follow --active --from-now --exclude "$AX_SESSION_ID"

That is the usual long-running coordinator stream: active workers only, no old turn replay, and no wakeups caused by the coordinator's own transcript. Use --exclude-self when AX_SESSION_ID is reliable in the caller's environment.

Fences, accept check, ask / reply

Fences are hard limits ax enforces, similar to resource limits for a pod. 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 the coordinator behavior: it 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. The one-command bootstrap:

ax coordinate "Add dark mode to this app. Done when: the toggle works and 'npm test' passes."

The behavior ships inside the binary; on first use it is written to ~/.config/ax/behaviors/coordinator.md, where your edits win on every later run. ax coordinate applies the reference guardrails (--write './.coordinator/**/*.md' --no-subagents --fence best-effort --max-workers 2 --max-depth 2 --keep-live --self-propel --attach); any launch flag you pass overrides them, and --harness / --small pick the harness and the small-model behavior variant. --self-propel is ax's outer loop: when the session ends a turn with its task unfinished, ax re-invokes it (pi/codex via their transcript's turn end, claude via its Stop hook's terminal marker) until the done criteria pass, it genuinely needs a human, or an idle cap trips.

A hand-rolled launch stays fully supported, e.g. to pin a model and budget (--behavior takes a behavior file path; --behavior-text takes inline text):

ax "Add dark mode to this app. Done when: the toggle works and 'npm test' passes." \
    --behavior ~/.config/ax/behaviors/coordinator.md \
    --write './.coordinator/**/*.md' --no-subagents --max-depth 2 \
    --label role=coordinator --model opus --max-cost 25 --max-workers 3

--write './.coordinator/**/*.md' is the fence. The coordinator can write only its own .coordinator/*.md state files and nothing else, and all mutating shell is denied, so every code change, config edit, and commit has to go through a worker it launches. That is what keeps the coordinator from editing the project directly.

--no-subagents turns off the in-process Task/Agent tools so every unit of work goes through ax claude, where it is a tracked session you can watch, attach to, and kill, with its own fence from its own launch. It is required because whether the write fence reaches a Task subagent depends on the Claude Code harness version, and on a build where it does not, a subagent would get an ungated shell. It is not a write sandbox: the write boundary is --write, and a fenced coordinator can still launch a writable worker by design. --max-depth 2 lets a worker launch its own workers, one tier deeper than the default.

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. Install dtach only on hosts that explicitly use the dtach hold backend. 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, ax wait, ax result, and the rest route the same way; ids are host-qualified, e.g. win01/<id>. m filters the list by machine and shows each host's status: online, offline, no ax, or old ax.

Remote compose is intentionally explicit. Choosing a remote target in the compose chooser aborts as unsupported rather than silently degrading to a plain launch. For remote task launches, run ax <harness> "task" --host NAME, run ax new on that host, or invoke the transport yourself.

# Native Windows host reached over OpenSSH + PowerShell
[[host]]
name      = "win01"
transport = "ssh -t win01"
shell     = "pwsh"
# headless = true  # use if remote interactive launch/attach is not verified

Use shell = "pwsh" when the remote sshd DefaultShell is PowerShell, so ax quotes forwarded arguments with PowerShell rules. ax config status reports each host's OS class, shell, ax version, wire version, and profile drift.

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.

Sandboxing with nono

nono is a zero-setup sandbox for AI agents: no daemon, no container, no VM. A sandboxed agent gets read/write access to its workspace and nothing else. Your SSH keys, your cloud credentials, and the rest of your disk are invisible to it, enforced by the kernel rather than by the harness's own permission prompts. ax integrates it as a launch axis:

ax claude "fix the flaky test" --sandbox

That wraps the harness in nono run --profile nolabs-ai/claude -- … using the registry profile matching the harness. To sandbox every task launch by default, set it once in ~/.config/ax/config.toml:

[sandbox]
backend = "nono"          # wrap every `ax <harness> "TASK"` launch
# profile = "you/custom"  # optional: override the default profile

[[harness]]
name = "claude"
sandbox_profile = "nolabs-ai/claude"   # optional per-harness override

--no-sandbox opts a single launch out. An explicit --sandbox with no nono on PATH fails loudly; the config default degrades to an unsandboxed launch with a warning, so a box without nono keeps working. The sandbox wraps only the harness process: attach, detach, ax send, heartbeats, and holders behave identically. Custom profiles come from nono profile init mine --extends nolabs-ai/claude; macOS and Linux are supported natively, Windows via WSL2.

Sandboxing composes with the fences below: the write fence shapes what a compliant agent does, the sandbox bounds what any agent can do, and disposable boxes bound the blast radius when everything else fails.

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 has little to steal and little 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.

Runnable recipes

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.