amux

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 (minimum 3.2). Each agent runs in its own tmux session for terminal isolation and persistence.

Quick start

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.

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

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

Platform Support

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

Development

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

Operations

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