mixpeek/amux: a self-hosted control plane for parallel Claude Code, Codex and Gemini workers

The problem amux solves: N agent CLIs, no shared state

Running one Claude Code session in a terminal is easy. Running five of them on the same repository is where the trouble starts. Each CLI keeps its own context, its own working directory assumptions and its own idea of what is done. Nothing stops two sessions from editing the same file, and nothing records which session produced which change. The usual workaround is a human in a tmux window cycling between panes, copying instructions by hand.

amux takes that workaround and makes it the product. The README describes it as "the open-source control plane for AI coding agents", and the unit of coordination is a shared kanban board rather than a chat window. Workers are Claude Code, Codex CLI, Gemini CLI, OpenCode or Ollama sessions that the server starts and tracks. The audience is narrow and specific: a developer or small team that already has at least one of those CLIs installed, is comfortable with tmux, and wants several of them working the same backlog without stepping on each other.

The claim worth examining is not that it runs agents in parallel. tmux already does that. It is that the fleet has state a single agent never had: who is live, what each worker owns, and a message ledger with a recorded sender.

A shared board with compare-and-swap claiming

The core mechanism is the task board. According to the README, claiming a card is a compare-and-swap operation, so two workers cannot grab the same card. That is a real design decision rather than a slogan: it moves the concurrency problem out of the agents and into the server, which is the only writer. The README also states that a card marked done requires evidence, and a card marked verified requires a peer check. Those two transitions are the difference between a to-do list and a workflow, because they encode what the fleet is allowed to assert.

The server itself is one Rust workspace with four crates. crates/amux-server is an axum HTTP API on port 8824 over HTTPS with a self-signed certificate, plain HTTP redirected, a single-writer SQLite store with an event journal, SSE plus delta sync, and the scheduler and orchestrator runtime. crates/amux-dashboard is a single-page app embedded into the server binary at build time, so no node or npm is needed to run it. crates/amux-cli provides amux-rs for board, workers, send, schedules and health. crates/amux-core holds the shared domain types.

Around the board sit the features that make a fleet legible. Workers can see each other and peek into a peer's terminal before interrupting. Messages between workers are origin-stamped, meaning the server records the true sender rather than trusting the text. Settings resolve card, then worker, then group, then global, and a group is a lane that shares memory, environment and gates. Schedules are cron-style recurring prompts such as daily at 9am or every 15m, and loops let a worker pace itself for an overnight run. A watchdog auto-compacts, restarts crashed sessions and replays the last message.

The README is explicit that the Rust server on port 8824 is the only server, and points to GET /api/debug/boundary as live proof, where a proxied: [] response means no request is being forwarded to anything else. That endpoint is a useful honesty check because it is falsifiable.

Installing amux and adding the first worker

The README gives a single command as the whole setup. The installer checks prerequisites (Rust toolchain, tmux, and it prompts before installing anything), builds the workspace, installs the server and CLI to ~/.local/bin, mints ~/.amux on first boot with the database, TLS material and auth token, waits for /health, and prints the dashboard URL, the token path and a CLI health command.

git clone https://github.com/mixpeek/amux && cd amux && ./install.sh

When it finishes you should see the dashboard at https://localhost:8824, the auth token at ~/.amux/auth_token, and a working health command. Open the dashboard and accept the self-signed certificate warning once. Requirements are tmux 3.2+ and at least one of Claude Code, Codex CLI or Gemini CLI.

The CLI check is the first thing to run, because it confirms both the binary and the TLS endpoint:

amux-rs --url https://localhost:8824 health

On Linux with systemd (Ubuntu 22.04+, Debian 11+, Fedora 36+), install.sh creates three user-level units, amux-server.service, amux-builder.service and amux-builder.timer. The README says the services are ready to start after the script completes, and gives these commands:

systemctl --user enable amux-server amux-builder.timer
systemctl --user start amux-server
journalctl --user -u amux-server -f

On distributions without systemd, the README says to run the server manually and shows the port variable:

AMUX_RS_PORT=8824 ~/.local/bin/amux-server-rs

Day to day, the Makefile is the interface. make run rebuilds release, installs the binary and lets the launchd-managed server pick it up; the README says the running server self-adopts in about five seconds. make dev runs against a scratch database at /tmp/amux-dev.db so migrations never touch live data. make status prints launchd state and the /health response. make test runs clippy across the workspace and the server test suite. Re-running ./install.sh upgrades in place and, per the README, never touches your data; ./uninstall.sh removes binaries and agents but leaves ~/.amux alone.

Where amux gets in the way

The installer is opinionated about the machine. It installs launchd agents on macOS or systemd user units on Linux, and the server watches its own binary mtime and exits so the supervisor can relaunch it. That is convenient on a laptop you control and awkward anywhere else: a container, a shared build host, or a CI runner will not have launchd, and the README's fallback is to run the server manually or wrap it in your own process manager. The Dockerfile.rust-base and Dockerfile.rust-build files exist in the tree, but the README does not walk through a container deployment, so that path is undocumented.

Platform support is uneven by the project's own description. macOS is labelled primary. Linux with systemd is supported. Other Linux distributions get binaries and nothing else. Windows does not appear in the platform list at all.

The self-healing story deserves scrutiny. The README states that the watchdog auto-compacts, restarts crashed sessions and replays the last message. It does not say what happens to a card that a crashed worker had already claimed under compare-and-swap, and it does not document rollback of partially applied work. Replaying the last message is not the same as replaying the last transaction, and a worker that died mid-edit can leave the repository in a state no message replay will fix. That gap is not a reason to avoid the tool; it is a reason to keep done and verified meaningful, since those transitions are the only evidence trail the system offers.

Finally, amux does not make an agent smarter. It coordinates sessions that are already competent. If your problem is that one Claude Code run produces bad code, adding four more workers multiplies the bad code.

amux compared with plain tmux and with hosted agent platforms

The nearest alternative is tmux plus shell scripts, which is what most people build first. tmux gives you panes, and a script can fan out prompts. What it does not give you is a compare-and-swap claim on a shared card, an origin-stamped message ledger, or a settings hierarchy that resolves card, worker, group, global. Those are server-side guarantees. A shell script can approximate the fan-out and none of the provenance, which is exactly the failure mode where two workers edit the same file and you cannot tell from the logs which one did it.

The other direction is a hosted agent platform that runs the workers for you. The difference in approach is where the state lives. amux is local-first and self-hosted: the README describes a SQLite store on your machine, a self-signed certificate on localhost, and an auth token in ~/.amux. That means your prompts, replies and delivery records stay on hardware you control, and it also means you own the uptime, the backups and the certificate warnings. A hosted platform inverts both halves of that trade.

There is a middle option worth naming because the repository includes it: mcp.json sits at the top level, and MCP is listed among the topics, so amux can be reached from an MCP-capable client rather than only from its own dashboard. The README does not document that integration in the text available, so treat it as something to inspect in the tree rather than a documented feature.

Maintenance, licence and what an upgrade costs you

The repository is not archived, and the last push was on 2026-09-10, which is recent. The most recent release listed is v0.9.108 from 2026-07-13. The version number itself is the useful signal here: a 0.9 line with frequent point releases suggests the API and the dashboard are still moving, and the changelog lives at amux.io/changelog rather than in the repository.

The upgrade mechanics are better than average for a self-hosted tool. ./install.sh upgrades in place, and the README says it never touches your data. make run rebuilds, reinstalls and lets the supervisor restart the server, which watches its own binary mtime and exits on change. Because the database is SQLite with a single writer and an event journal, the risky part of any upgrade is a schema migration, and the project provides make dev specifically to run against a scratch database at /tmp/amux-dev.db so migrations can be exercised before they touch live data. That is the upgrade procedure to follow: make dev first, then make run.

On licensing, the repository's licence file is described in the README as MIT + Commons Clause, while the repository metadata reports NOASSERTION. Those two do not agree, and the Commons Clause is the part that changes behaviour: the README says the software is free to use, modify and self-host, and that commercial resale requires a separate licence. Read the LICENSE file in your own checkout before building a product on top of it. This is a description of what the documents say, not legal advice.

Editorial conclusion

Adopt amux if you already run Claude Code, Codex CLI or Gemini CLI in tmux and the pain is coordination rather than model quality: the atomic claim on the board and the origin-stamped messaging are the parts a shell script will not give you. Do not adopt it if you want a hosted service, if you cannot run tmux 3.2+ on the host, or if you plan to resell the result, since the licence is MIT plus Commons Clause and commercial resale needs a separate licence. Before trusting it with real work, verify two things in your own checkout: that GET /api/debug/boundary returns proxied: [] on the Rust server on port 8824, and that the watchdog actually restarts a killed session, because the README describes self-healing but does not document what happens to a card a crashed worker had already claimed.

Frequently asked questions

Official sources

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