aggregate lifecycle
Launch, park, restart, remove, doctor, and reconcile both modes, with canonical --thread, --workdir, and --workspace selectors.
Complements Amp Agents Anywhere
Pin. Launch.
Park. Teardown.
Amp runs your agents anywhere. amux manages interactive workers by canonical thread, no-TUI runners by
canonical workdir, and both inside same-named tmux workspaces — with explicit side effects safe to hand to agents.
A shared lifecycle vocabulary.
Launch, restart, park, shelve, and teardown name distinct states instead of interchangeable ways to “stop” work. This is the public glossary: click a term to see its meaning, illustrative effect, and side-effect domains.
Touches
Latest release: v0.2.1.
Current new work uses native child threads. The pre-cutover lifecycle cards below describe compatibility/drain support retained by this release, not new-work features.
JSON v1 + --dry-run
Stable machine-readable envelopes and mutation previews make agent operation inspectable before side effects.
pre-cutover group drain
Compatibility-only durable work groups preserve exact persisted member and coordinator identity while already-bound pre-cutover flows drain; they are not a native new-work feature.
pre-cutover report drain
Compatibility-only durable reports and finish authorization continue exact persisted pre-cutover obligations; native-created threads receive neither.
pre-cutover callback drain
Compatibility-only callback leases reverify the exact pane and process before waking an already-bound pre-cutover report flow; no callback lease is created for native work.
runner maintenance
First-class maintenance for amp --no-tui runners, which never own remote agent threads.
workdir-bound runners
Runner workdirs may be Git worktrees or any other existing directory, while exact tmux and process ownership remains fail-closed.
Your agent already speaks it.
The bundled /amux skill teaches agents canonical selectors, side-effect boundaries, and safe routing. Health,
coordination, sprawl, and finish are skill-only workflows, not CLI commands.
$ npx skills add zainfathoni/amux --skill amux --global
See the skill guide and trigger reference.
“Pin it”
amux worker pin --workspace … --window … --workdir … --thread …“Park it”
amux worker park --current“Shelve this”
amux shelve --thread …“Restore my workspace”
amux launch --workspace …“Doctor amux”
amux doctor --workspace … (read-only)“Coordinate child threads”
authenticated native creation on exact executor/workdir · native reply routing and waiting · no Amux adoption or lifecycle state“/amux health”
skill-only · read-only responsiveness check“/amux sprawl”
skill-only · coordinated native child threads“/amux finish”
skill-only · pre-cutover existing-worker drain; teardown lastA binary, Amp CLI,
and tmux.
No daemon, no database. The installer verifies the published checksum and atomically installs the Linux or macOS arm64/amd64 release at ~/.local/bin/amux.
Other options: Homebrew · manual release fallback · build from source
$ curl -fsSL https://amux.zainf.dev/install.sh | sh
# verify PATH selection and installation health
$ ~/.local/bin/amux install doctor