Screenshot 2026年01月20日 at 1 00 23 AM

TUI for easily running parallel coding agents

Latest release License Go version Discord

Quick start · How it works · Features · Configuration

amux TUI preview

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 internal/app/ARCHITECTURE.md for lifecycle, PTY flow, tmux tagging, and persistence invariants. Message boundaries and command discipline are documented in internal/app/MESSAGE_FLOW.md.

• 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

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

Create .amux/workspaces.json in your project to run setup commands for new workspaces:

{
 "setup-workspace": [
 "npm install",
 "cp $ROOT_WORKSPACE_PATH/.env.local .env.local"
 ]
}

Workspace metadata is stored in ~/.amux/workspaces-metadata/<workspace-id>/workspace.json, and local worktree directories live under ~/.amux/workspaces/<project>/<workspace>.

Assistant profiles can be configured in ~/.amux/config.json:

{
 "assistants": {
 "openclaw": {
 "command": "openclaw",
 "interrupt_count": 1,
 "interrupt_delay_ms": 0
 }
 }
}

For automation and skill-driven control (for example an agent orchestrator), prefer the headless CLI with --json.

Discovery and contract:

amux --json capabilities

Recommended mutation pattern:

1. Use --idempotency-key <stable-key> on mutating commands.
2. Retry safely on transport/process failures with the same key.
3. Treat JSON envelope fields (ok, error.code, data) as the API contract.

Async send pattern:

# enqueue prompt
amux --json agent send <session_or_agent> --text "..." --enter --async
# poll status
amux --json agent job status <job_id>
# or wait until terminal state
amux --json agent job wait <job_id> --timeout 30s --interval 200ms
# optional cancellation (pending jobs only)
amux --json agent job cancel <job_id>

Graceful stop pattern:

amux --json agent stop <session_or_agent> --graceful --grace-period 1200ms

This sends Ctrl-C first, then force-kills if the session is still running after the grace period.

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).