amux

amux runs coding-agent sessions on a machine. Each session is a named, long-running agent in its own git worktree, living inside tmux, with a web dashboard that shows every session at once. It is the per-machine layer of the multi-machine stack : one amux per machine, optionally tied together by hcom .

It is deliberately small — a launcher script, a Python dashboard server, and a remote-control script — so there is little to break and nothing to learn beyond a handful of verbs.

What it gives you

• Isolated sessions. Each agent works in its own git worktree, so several can edit the same repository in parallel and you review their branches separately.
• Persistence. Sessions live in tmux, so they keep running after you detach, close the terminal, or drop the SSH connection. Reattach later, right where it was.
• A dashboard. amux serve puts every session — output, status, controls — on one web page.
• Remote control. From a hub machine, amux-remote drives any other machine’s amux over its HTTP API. See connecting machines .

Install

amux is three files that must sit in the same directory on your PATH (the launcher finds the server next to itself):

git clone --depth 1 https://github.com/mixpeek/amux ~/amux-src
install -m 755 ~/amux-src/amux ~/amux-src/amux-remote ~/amux-src/amux-server.py ~/.local/bin/
amux --version

Needs tmux, git, and python3 present, plus at least one coding agent (Claude Code , codex, gemini, or opencode ) installed and signed in.

Core commands

Anything amux doesn’t recognize on register/exec is passed straight to the coding agent, so you use the agent’s own flags (--model, --continue, --append-system-prompt, …). The two helper scripts — amux-run and amux-attach — wrap the two things you do most.

Long lists get noisy — amux ls -c prints a compact one-screen grid, and amux ls | less -R pages the full list while keeping colors.

Providers — which agent a session runs

Each session runs one coding agent, and amux supports four. Pick it with --provider on register / exec (persisted with the session), change it later with amux provider NAME <p> (with the session stopped), or override a single start with amux start NAME --provider <p> (not persisted). The remote mirror is identical: amux-remote BOX exec NAME … --provider <p> and amux-remote BOX provider NAME [<p>].

A missing provider binary fails loudly at amux start (a clear error naming the binary) instead of leaving a dead tmux pane, and amux --help shows which providers are installed on the current machine.

Companion commands

A set of small wrappers rides alongside amux for working across many sessions and machines: amux-remote (drive a named box over its API), amux-all (one list across every machine), amux-up (start if needed, then attach), ccjump (fuzzy-jump to any active session, local or remote), amux-rename, amux-convos, amux-reauth, check-claude-auth, amux-tabs, plus amux-config (manage the per-machine configs) and amux-doctor (is this machine actually set up right?).

They ship in the public companion repo — download the package or clone amux-nui-public (opens in new tab) and run ./install.sh to get them all (including an enhanced amux-remote, symlinked into place). amux-tools has the full table and install details; Connect machines walks through pointing them at your machines.

amux ls only ever shows the box you’re on, so a remote listing should say which machine it’s from. amux-remote <box> ls leads with that, and -c gives the same compact grid as amux ls -c:

$ amux-remote myhub ls -c
myhub (remote) · 8 sessions · 3 ● running
https://100.x.y.z:8822  · ssh myhub

 1 ● webapp   4 ○ docs      7 ○ infra
 2 ● api      5 ○ scratch   8 ○ notes
 3 ● worker   6 ○ archive

amux-all stacks that view for every configured machine — local first, then each remote — so one command shows the whole fleet, compact by default.

Two behaviors that trip people up

Resuming after a restart

A session’s metadata records which conversation to resume, so a restart picks up where it left off instead of starting blank. If the recorded target is stale or fails to launch, start falls back automatically — first to the newest substantive conversation on disk for the working directory, then to a fresh start — so a plain start recovers context on its own. This also covers the case where the pane’s shell was exited manually (the tmux pane is left dead): start detects the dead pane, replaces it, and resumes normally. Nothing is ever deleted: a lost conversation can still be recovered with the agent’s own --resume ID run in that directory.

If a start truly fails, the error now includes the last lines the pane actually printed — the agent’s own error message — instead of a bare “failed to start”.

To see the conversations and pick the right one deliberately, use amux-convos NAME — Find and resume the right conversation covers it, along with the trap where a resumed session shows an old 401 / Please run /login from its transcript that looks like a live auth failure but isn’t.

The dashboard

amux serve 8822 --bind 127.0.0.1,<private-IP>

It serves a self-signed certificate by default; point it at a real certificate (for example one from tailscale cert) for a clean green lock. Run it from a service manager (systemd / launchd) so it comes back after a reboot.

Where things live

~/.amux/ holds the session database, the dashboard token, TLS certificates, and per-session state. Back it up if the sessions matter; never commit the token anywhere public.

Next

• Hands-on from scratch: Run agents on one machine .
• Tie machines together: hcom and Connect machines .