TUI for easily running parallel coding agents
Quick start · How it works · Features · Configuration
 ## What is amux? amux is a terminal UI for running multiple coding agents in parallel with a workspace-first model that can import git worktrees. ## Prerequisites amux requires [tmux](https://github.com/tmux/tmux) (minimum 3.2). Each agent runs in its own tmux session for terminal isolation and persistence. ## Quick start ```bash brew tap andyrewlee/amux brew install amux ``` Or via the install script: ```bash curl -fsSL https://raw.githubusercontent.com/andyrewlee/amux/main/install.sh | sh ``` Or with Go (requires Go 1.26 or newer; contributors should use the patched toolchain pinned in `go.mod`): ```bash go install github.com/andyrewlee/amux/cmd/amux@latest ``` Then run `amux` to open the dashboard. ## How it works Each workspace tracks a repo checkout and its metadata. For local workflows, workspaces are typically backed by git worktrees on their own branches so agents work in isolation and you can merge changes back when done. ## Architecture quick tour Start with [`ARCHITECTURE.md`](ARCHITECTURE.md) for the repo-level package map and dependency direction. Then `internal/app/ARCHITECTURE.md` covers lifecycle, PTY flow, tmux tagging, and persistence invariants, and `internal/app/MESSAGE_FLOW.md` documents message boundaries and command discipline. External orchestration: the supported tmux-level contract is documented in [docs/ORCHESTRATION.md](docs/ORCHESTRATION.md). ## Features - **Parallel agents**: Launch multiple agents within main repo and within workspaces - **No wrappers**: Works with Claude Code, Codex, Gemini, Amp, OpenCode, and Droid - **Keyboard + mouse**: Can be operated with just the keyboard or with a mouse - **All-in-one tool**: Run agents, view diffs, and access terminal ## Configuration Create `.amux/workspaces.json` in your project to define commands that amux runs for its workspaces: ```json { "setup-workspace": [ "npm install", "cp $ROOT_WORKSPACE_PATH/.env.local .env.local" ], "run": "npm start", "archive": "tar -czf archive.tar.gz ." } ``` - `setup-workspace` — commands run once when a new workspace is created. - `run` — the command started for a workspace's run script. - `archive` — the command run when a workspace is archived. ### Environment available to workspace scripts `setup-workspace`, `run`, and `archive` scripts run with these variables set, in addition to your normal shell environment: | Variable | Meaning | |----------|---------| | `AMUX_WORKSPACE_NAME` | The workspace name | | `AMUX_WORKSPACE_ROOT` | The workspace worktree path | | `AMUX_WORKSPACE_BRANCH` | The workspace's git branch | | `ROOT_WORKSPACE_PATH` | The source repository root (also shown in the example above) | | `AMUX_PORT` | An allocated per-workspace port — bind dev servers here to avoid collisions across parallel workspaces | | `AMUX_PORT_RANGE` | The `start-end` port range allocated to this workspace | Because these commands come from the repository, amux runs them only after you trust the repo. The first time a repo's `.amux/workspaces.json` would run (and every time its contents change), amux records the approved content of the file; until then those project-supplied scripts are skipped and you are notified, rather than executing arbitrary commands chosen by the repo's author. Editing `.amux/workspaces.json` invalidates the approval, so changed commands are re-gated until you trust the file again. (Run/archive scripts you enter yourself in the amux UI are your own input and are never gated.) Workspace metadata is stored in `~/.amux/workspaces-metadata/