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

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:

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

Platform Support

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

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