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 (requires Go 1.26 or newer; contributors should use the patched toolchain pinned in go.mod):

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.

External orchestration: the supported tmux-level contract is documented in 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:

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

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.

Assistants: the AI agents amux can launch are configured per-user in ~/.amux/config.json. You can add your own or override a built-in — see docs/CONFIG.md.

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
./scripts/install-hooks.sh   # one-time: enables the pre-commit + pre-push git hooks
make lint-tools              # one-time: builds the pinned golangci-lint into ./.cache/bin
make run

Run ./scripts/install-hooks.sh once after cloning. It points core.hooksPath at .githooks, enabling the pre-commit fmt/lint/file-length checks and the pre-push lint-parity gate the project relies on for quality.

Run make lint-tools once before your first make devcheck or git commit. It builds the linter pinned in .golangci-version into the gitignored ./.cache/bin; a stock golangci-lint from PATH may be a different version from CI and produce different diagnostics. See LINTING.md and CONTRIBUTING.md for details.

Operations

• Logs are written to ~/.amux/logs/amux-YYYY-MM-DD.log (default retention 14 days). Override retention with AMUX_LOG_RETENTION_DAYS.
• Log verbosity: set AMUX_LOG_LEVEL=debug (accepts debug/info/warn/error; default info) to change what gets written to the log — debug is the first thing to try when reporting or diagnosing a problem.
• Attached-tab limit: set AMUX_MAX_ATTACHED_AGENT_TABS (default 6; 0 disables the limit) to change how many agent tabs keep live PTYs attached concurrently.
• Terminal-tab limit: set AMUX_MAX_ATTACHED_TERMINAL_TABS (default 6; 0 disables the limit) to change how many sidebar terminals keep live PTYs attached; least-recently-used background terminals detach automatically, stay alive in tmux, and re-attach when their workspace is selected.
• Git hooks: amux runs git with repo hooks and core.fsmonitor disabled so a checked-out repository cannot execute code just because amux touched it; set AMUX_ALLOW_GIT_HOOKS=1 if your workflow needs repo hooks (e.g. git-lfs).
• OSC 52 clipboard: set AMUX_ENABLE_OSC52_CLIPBOARD=1 to let agent terminal output copy to your clipboard via OSC 52 (off by default because terminal output is untrusted; payloads over 64 KiB are ignored).
• 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). The trace captures both directions of the pipeline — agent→amux output is tagged RECV and amux→agent input (keystrokes, pastes, the delayed Enter/CR) is tagged SEND — so send-path issues like a dropped Enter can be debugged at the byte level.