TUI for easily running parallel coding agents

Quick start · How it works · Features · Configuration

amux is a terminal UI for running multiple coding agents in parallel with a workspace-first model that can import git worktrees.

amux requires tmux (minimum 3.2). Each agent runs in its own tmux session for terminal isolation and persistence.

brew tap andyrewlee/amux
brew install amux

Or via the install script:

curl -fsSL https://raw.githubusercontent.com/andyrewlee/amux/main/install.sh | sh

Or with Go:

go install github.com/andyrewlee/amux/cmd/amux@latest

Then run amux to open the dashboard.

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.

Start with 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.

• 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

Create .amux/workspaces.json in your project to define commands that amux runs for its workspaces:

{
  "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.

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/<workspace-id>/workspace.json, and local worktree directories live under ~/.amux/workspaces/<project>/<workspace>. Trusted-repo approvals are recorded in ~/.amux/trusted-scripts.json.

AMUX requires tmux and is supported on Linux/macOS. Windows is not supported.

git clone https://github.com/andyrewlee/amux.git
cd amux
make run

• Logs are written to ~/.amux/logs/amux-YYYY-MM-DD.log (default retention 14 days). Override retention with AMUX_LOG_RETENTION_DAYS.
• Perf profiling: set AMUX_PROFILE=1 to emit periodic timing/counter snapshots; adjust cadence with AMUX_PROFILE_INTERVAL_MS (default 5000).
• pprof: set AMUX_PPROF=1 (or a port like 6061) to expose net/http/pprof on 127.0.0.1.
• Debug signals: set AMUX_DEBUG_SIGNALS=1 and send SIGUSR1 to dump goroutines into the log.
• PTY tracing: set AMUX_PTY_TRACE=1 or a comma-separated assistant list; traces write to the log dir (or OS temp dir if logging is disabled).