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.

Both write actions are available from the UI, each behind an explicit confirmation:

• Commit — press c in the Changes sidebar to stage everything in the workspace and commit it with a message you type. The commit lands on the workspace's own branch; amux never pushes.
• Merge — press M on a workspace row in the dashboard to merge its branch into its base with git merge --no-ff. The merge happens in the project's primary checkout, so amux first checks that the base branch is already checked out there and refuses otherwise rather than moving your HEAD. On a conflict it lists the conflicted files and offers to abort; resolving them is yours to do in the terminal.

Note that amux runs git with repository hooks disabled (see AMUX_ALLOW_GIT_HOOKS below), so your own pre-commit or pre-merge hooks will not fire on these actions.

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. Press r in the Changes sidebar to start it, and r again to stop it; a [run] marker sits next to the branch name while it is live. Bind your dev server to AMUX_PORT so parallel workspaces don't collide.
• archive — the command run when a workspace is archived, i.e. just before its worktree is deleted. It runs to completion (up to two minutes) in the worktree while that directory still exists, after the run script has been stopped. It is best-effort: if it fails or the repo isn't trusted yet, amux warns you and deletes the workspace anyway, so a broken archive script can never strand a workspace. Write it to tolerate running twice — if the delete itself fails after the script has run, retrying the delete runs it again.

Environment available to workspace scripts

setup-workspace, run, and archive scripts run with these variables set, in addition to your normal shell environment:

Variable	Meaning
AMUX_WORKSPACE_NAME	The workspace name
AMUX_WORKSPACE_ROOT	The workspace worktree path
AMUX_WORKSPACE_BRANCH	The workspace's git branch
ROOT_WORKSPACE_PATH	The source repository root (also shown in the example above)
AMUX_PORT	An allocated per-workspace port — bind dev servers here to avoid collisions across parallel workspaces
AMUX_PORT_RANGE	The start-end port range allocated to this workspace

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 to run. git-lfs works either way — its clean/smudge filters are never disabled, and amux points core.hooksPath at /dev/null (not at an empty value) so lfs cannot leave stray hook files in a workspace root.
• 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.