Run agents on one machine

This is the ground floor: one machine, one or more agent sessions, each isolated in its own git worktree, all visible in a browser. Everything later — more machines, a coordination bus — builds on this, so it is worth getting comfortable here first. A “machine” is any computer you can use, including your laptop.

What you need first

• tmux, git, and python3. amux is a shell script plus a Python server, and it runs each session inside tmux, so these three have to be present. Install them with your package manager (for example, brew install tmux on macOS, or apt install tmux git python3 on Debian/Ubuntu).
• A coding agent, installed and signed in. This guide uses Claude Code ; opencode works the same way. Install it and log in once before you start, so the agent can launch on its own without stopping to authenticate.

Install amux

amux is three files: a launcher (amux), a dashboard server (amux-server.py), and a remote-control script (amux-remote). They must sit in the same directory on your PATH, because the launcher looks for 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

~/.local/bin needs no sudo and is already on most PATHs. Use /usr/local/bin instead if you want a system-wide install.

Start your first session

A session is a named, long-running agent tied to a directory. Register one and start it:

amux register myapp --dir ~/code/myapp --model opus
amux start myapp        # opens the agent in tmux and attaches you to it

Detach and leave it running the tmux way — Ctrl-b then d. The session keeps going; come back any time with amux attach myapp. List everything with amux ls, where a * next to a session means it is running.

Worktrees: why several agents don’t collide

When a session works inside a git repository, amux gives it its own git worktree — a separate checked-out copy of the repository that shares the same history. Two agents can edit what looks like the same project at once because each is really editing its own worktree, and you review and merge their branches like any other change. For example, one agent can add a feature while a second fixes a bug in the same repo, and neither sees the other’s half-finished edits. That isolation is the main reason running several agents at once is safe rather than chaotic.

Two scripts that make this easy

amux has a verb for everything, but day to day you do two things: start a session with some options, and attach to one. These two scripts wrap exactly that. The split is deliberate — starting and attaching are separate steps, so you can fire off several agents and then look in on whichever you want.

amux-run — start (or restart) a session, detached

Everything after the name passes straight through to the coding agent, so you use the agent’s own flags, written out in full:

amux-run api  --model opus --continue
amux-run docs --model sonnet --append-system-prompt "Documentation writer"

It starts the session detached — it runs in the background instead of taking over your terminal — which is what lets you start several and attach later. Re-running it with the same name restarts that session with the new options.

#!/usr/bin/env bash
# amux-run NAME [agent flags...] — start NAME in the current directory, detached.
set -euo pipefail
[ $# -ge 1 ] || { echo "usage: amux-run NAME [agent flags...]" >&2; exit 1; }
name="$1"; shift
amux stop "$name" >/dev/null 2>&1 || true            # clean restart so flags + dir apply
amux register "$name" --dir "$PWD" "$@" >/dev/null
amux start "$name" </dev/null >/dev/null 2>&1 || true # </dev/null forces a detached start
amux info "$name" >/dev/null 2>&1 \
  && echo "started '$name' (detached) — attach with: amux-attach $name" \
  || { echo "amux-run: failed to start '$name'" >&2; exit 1; }

One detail is worth understanding, because it is what keeps start and attach independent. amux start normally drops you straight into the session. Redirecting its input from </dev/null makes that attach a no-op — the session is still created and left running, you just are not pulled into it.

amux-attach — attach to a running session

#!/usr/bin/env bash
# amux-attach NAME — attach to a running session (detach: Ctrl-b then d).
set -euo pipefail
[ $# -ge 1 ] || { echo "usage: amux-attach NAME" >&2; exit 1; }
exec amux attach "$1"

Install both:

chmod +x amux-run amux-attach
mv amux-run amux-attach ~/.local/bin/

The everyday loop is then two commands:

cd ~/code/myapp
amux-run myapp --model opus      # start it (and others) in the background
amux-attach myapp                # look in; Ctrl-b d to step out, it keeps running

Watch everything from a browser

amux serve starts the dashboard: every session, its live output, and controls to start, stop, and send input, all in one page. Bind it to the private network, not to every interface:

amux serve 8822 --bind 127.0.0.1,<this-machine's-private-IP>

The default bind is 0.0.0.0, which means every interface, including any public one — do not leave it there. On a Tailscale network, bind to the machine’s tailnet address and reach the dashboard at https://<machine>:8822. amux serves a self-signed certificate out of the box, which works but throws a browser warning; for a clean certificate, point amux at one from your network’s HTTPS (for example, tailscale cert). To survive reboots, run amux serve from a service manager — systemd on Linux, a launchd agent on macOS — rather than by hand.

Where to go next

• Add machines and let agents coordinate: Connect machines with hcom .
• Put a local model on the routine work: Local and frontier models .
• Every command in one place: amux cheat sheet .