https://github.com/andyrewlee/amux
TUI for easily running parallel coding agents
https://github.com/andyrewlee/amux
agent-coordination agent-orchestration agent-swarm ai-orchestration conductor git-worktree parallel-agents parallelexecution terminal-ui tui worktree worktrees
Last synced: 12 days ago
JSON representation
TUI for easily running parallel coding agents
- Host: GitHub
- URL: https://github.com/andyrewlee/amux
- Owner: andyrewlee
- License: mit
- Created: 2025-12-31T01:57:28.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-07T22:46:17.000Z (15 days ago)
- Last Synced: 2026-03-08T04:10:44.914Z (15 days ago)
- Topics: agent-coordination, agent-orchestration, agent-swarm, ai-orchestration, conductor, git-worktree, parallel-agents, parallelexecution, terminal-ui, tui, worktree, worktrees
- Language: Go
- Homepage:
- Size: 2.24 MB
- Stars: 42
- Watchers: 0
- Forks: 2
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
- awesome-tuis - amux
README
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](https://github.com/tmux/tmux) (minimum 3.2). Each agent runs in its own tmux session for terminal isolation and persistence.
## Quick start
```bash
brew tap andyrewlee/amux
brew install amux
```
Or via the install script:
```bash
curl -fsSL https://raw.githubusercontent.com/andyrewlee/amux/main/install.sh | sh
```
Or with Go:
```bash
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:
```json
{
"setup-workspace": [
"npm install",
"cp $ROOT_WORKSPACE_PATH/.env.local .env.local"
]
}
```
Workspace metadata is stored in `~/.amux/workspaces-metadata//workspace.json`, and local worktree directories live under `~/.amux/workspaces//`.
Assistant profiles can be configured in `~/.amux/config.json`:
```json
{
"assistants": {
"openclaw": {
"command": "openclaw",
"interrupt_count": 1,
"interrupt_delay_ms": 0
}
}
}
```
## Headless CLI for Skills
For automation and skill-driven control (for example an agent orchestrator), prefer the headless CLI with `--json`.
Discovery and contract:
```bash
amux --json capabilities
```
Recommended mutation pattern:
1. Use `--idempotency-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:
```bash
# enqueue prompt
amux --json agent send --text "..." --enter --async
# poll status
amux --json agent job status
# or wait until terminal state
amux --json agent job wait --timeout 30s --interval 200ms
# optional cancellation (pending jobs only)
amux --json agent job cancel
```
Graceful stop pattern:
```bash
amux --json agent stop --graceful --grace-period 1200ms
```
This sends `Ctrl-C` first, then force-kills if the session is still running after the grace period.
## Development
```bash
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).