amux: a Rust control plane for running parallel Claude Code, Codex and Gemini workers

What problem amux solves, and who it is written for

Running one coding agent in a terminal is easy. Running five is a scheduling problem. Each CLI session (Claude Code, Codex, Gemini CLI, OpenCode, Ollama) holds its own context, its own working directory and its own idea of what is finished. The README lists what it calls the fleet's advantages over a single agent: a shared kanban board where claiming is compare-and-swap so two workers cannot take the same card, peer visibility so a worker can look into another worker's terminal before interrupting, and origin-stamped messaging where the server records the true sender.

The intended user is a developer or small team already paying for at least one agent CLI and already comfortable with tmux. amux does not replace the agent; it wraps the session. If you run a single agent interactively and never schedule anything, the server, the SQLite store and the watchdog are overhead with no payoff. The project is also self-hosted and local-first by design, so it suits people who want the task ledger and message history on their own disk rather than in a vendor's cloud.

The mechanism: one Rust server, four crates, tmux underneath

The repository is a single Rust workspace with four crates. crates/amux-server is an axum HTTP API on port 8824 over HTTPS with a self-signed certificate, with plain HTTP redirected. It holds a single-writer SQLite store with an event journal, serves SSE plus delta sync, runs the scheduler and orchestrator, and embeds the dashboard. crates/amux-dashboard is the SPA compiled into the server binary at build time, which is why the README says no node or npm is needed. crates/amux-cli provides the amux-rs command. crates/amux-core holds shared domain types.

The data flow is card-centric. A task lives on the board; a worker claims it through a compare-and-swap operation; the scheduler and orchestrator runtime decide what runs when; the event journal records prompts, replies and deliveries as ledger rows. Settings resolve in a fixed order the README gives as card, then worker, then group, then global. Groups are called lanes and share memory, environment and gates. The README also states that done requires evidence and verified requires a peer check, which means the board is not just a to-do list: two of its states are gated on artefacts rather than on a worker's own claim of success.

One detail worth noting for anyone reading the code: the README addresses a question it expects readers to ask, which server is real. The answer is the Rust server in crates/amux-server on port 8824, and the stated live proof is GET /api/debug/boundary reporting proxied: []. The same binary answers the retired port 8822 while a compatibility bind survives. The Python predecessor is described as gone. That kind of note usually means the project went through a rewrite and users hit stale documentation, so treat the boundary endpoint as the check rather than the prose.

Installing it: one script, then short make targets

The quickstart is a clone plus an install script. The README gives it as: git clone https://github.com/mixpeek/amux && cd amux && ./install.sh. According to the README, the installer checks for the Rust toolchain and tmux, prompts before installing anything, builds the workspace, installs the server and CLI to ~/.local/bin, loads launchd agents on macOS, mints ~/.amux (DB, TLS, auth token) on first boot, waits for /health, and prints the dashboard URL, the auth token path and a CLI health command: amux-rs --url https://localhost:8824 health. You open https://localhost:8824, accept the self-signed certificate warning once, and add a worker from the dashboard.

Day-to-day commands are make targets. make run rebuilds and reinstalls, and the README states the running server self-adopts in about five seconds. make dev runs against a scratch database for migration work. make status checks launchd and /health. make restart kicks the launchd-managed server. make check runs cargo check plus a JavaScript syntax pass. make test runs clippy and cargo test. The stated rule is that make run is the command after git pull, and make dev is for migrations or features you do not want touching the live database.

On Linux with systemd (Ubuntu 22.04+, Debian 11+, Fedora 36+), the installer creates three user-level units: amux-server.service, amux-builder.service and amux-builder.timer, the timer checking every 60 seconds. The README then shows systemctl --user enable amux-server amux-builder.timer followed by systemctl --user start amux-server, with journalctl --user -u amux-server -f for logs. On other distributions the documented fallback is to run the server by hand with AMUX_RS_PORT=8824 ~/.local/bin/amux-server-rs. Requirements are tmux 3.2+ and at least one of Claude Code, Codex CLI or Gemini CLI.

Where the design constrains you

The installer is the sharpest limitation. It assumes launchd on macOS or systemd on Linux. The README names three systemd distributions and then says that for other Linux distributions you run the server manually or wrap it in your own process manager. That is a real gap: the self-healing watchdog, the auto-rebuild builder service and the automatic restart behaviour described in the README are tied to those two init systems. On a distribution without systemd you get the binary and the dashboard, not the supervision story.

The single-writer SQLite store is the second constraint. It is what makes the event journal and the compare-and-swap claim straightforward, and it is also a ceiling on how the server scales. Nothing in the supplied material describes a multi-node or replicated deployment, so the reasonable reading is that amux is a single-host tool. If your agents need to run across several machines, this is the wrong shape.

The licence is the third. The repository metadata reports the licence as NOASSERTION while the README badge and text say MIT plus Commons Clause, and the README states that commercial resale requires a separate licence. Those two signals do not agree, so read LICENSE yourself rather than trusting either the badge or the metadata. Nothing here is legal advice, but the practical consequence is that self-hosting and modification are described as free while reselling is not, which rules amux out for anyone who wants to build a paid hosted product on top of it.

Finally, the versioning. The most recent release in the supplied material is v0.9.108, dated 2026-07-13. A 0.9 line with a three-part patch number suggests frequent small releases. The README points to a changelog at amux.io/changelog, and that is where you should look before pinning a version, because the material here gives no compatibility guarantees between releases.

How it differs from a hand-rolled tmux plus cron setup

The obvious alternative is the one most people already have: tmux windows, a shell script per agent, and cron for anything recurring. That approach gives you parallel sessions and scheduling, and it costs nothing to adopt. The difference is in what it does not give you. A cron job cannot refuse to start a second copy of a task because another worker already claimed it. A shell script cannot tell a worker who sent a message, because the sender is whatever the script passed in. And a cron job has no notion of evidence or peer verification before a task is marked complete.

amux moves those three things into the server. Claiming becomes compare-and-swap, so the duplicate-work failure mode is handled at the store rather than in your script. Messaging becomes origin-stamped, with the README stating that the server records the true sender, so provenance is a fact rather than a claim. Task completion becomes gated: done requires evidence and verified requires a peer check. The cost of that move is the server itself: a Rust binary, a SQLite database under ~/.amux, a TLS certificate, an auth token, and an init-system dependency. You are trading a folder of shell scripts for a service you have to upgrade and supervise.

There is a middle option worth naming: keep tmux and cron, and add only the parts you need, such as a lock file for task claiming. That gets you the duplicate-work fix without the control plane. It does not get you the ledger, the peer check, or the ability to type into a running session from a phone, which the README lists as steering from the dashboard or phone.

Upgrading, data safety and what to check before you commit

The README makes two explicit promises about upgrades. Re-running ./install.sh upgrades in place and never touches your data. ./uninstall.sh removes the binaries and agents and leaves ~/.amux alone. If those hold, the maintenance cost is mostly the rebuild cycle: make run after a git pull, with the launchd-managed server picking up the new binary automatically, or the amux-builder.service and amux-builder.timer doing the same on systemd every 60 seconds. That timer is also a thing to think about: an automatic rebuild check running every minute on a developer machine is convenient and is still a background process you did not write.

What the material does not tell you is how migrations behave across a 0.9.x series, whether the SQLite schema changes between releases, or what happens if a rebuild lands while workers are mid-task. The README's answer to the last question is the self-adoption behaviour of make run, and its answer to migration risk is make dev against a scratch database. Those are the two levers to use: test the upgrade on a scratch DB with make dev before pointing make run at the live one, and keep a copy of ~/.amux outside the install directory so that uninstall and reinstall are genuinely non-destructive.

One more check belongs on the list. The README's own framing of which server is real suggests that stale documentation is a known hazard for this project, and the mismatch between the NOASSERTION metadata and the MIT plus Commons Clause badge is a second instance of the same problem. Verify against the running system: GET /api/debug/boundary should report proxied: [], the health endpoint should answer after a reboot, and the CLI subcommands listed in the README (board, workers, send, schedules, health) should exist in the binary you installed.

Editorial conclusion

Adopt amux if you already run more than one coding-agent CLI session at a time and want the shared board, atomic claiming and origin-stamped messaging that a plain tmux setup cannot give you. Do not adopt it if you are on a Linux distribution without systemd and are unwilling to run the server manually, or if you need a licence that permits commercial resale, because MIT plus Commons Clause does not. Before committing, verify four things: that GET /api/debug/boundary reports an empty proxied list on your build, that the three systemd user units or the launchd agents start cleanly after a reboot, that ~/.amux survives a re-run of ./install.sh, and that the v0.9.108 release notes match the CLI subcommands your scripts will call.

Official sources

1. Issues
2. mixpeek/amux on GitHub
3. Project website
4. README
5. Releases