Multi-agent orchestration through terminal panes — spawn, coordinate, and observe AI agents in split panes with file-based communication.
Terminal backends: tmux (default) | kitty — see docs/terminal-backends.md
┌──────────────────────┬───────────────────┐
│ │ planner (gemini) │
│ main agent ├───────────────────┤
│ (claude/codex) │ coder (claude) │
│ ├───────────────────┤
│ │ reviewer (codex) │
└──────────────────────┴───────────────────┘
automux lets you run multiple AI coding agents in parallel — each in its own terminal pane, git worktree, and branch. A main agent orchestrates subagents through files, not fragile pane scraping. You watch everything happen live in your terminal.
Supports: Claude Code, Codex CLI, Gemini CLI — mix and match in the same session. Backends: tmux (persistent sessions, Linux/macOS) or kitty (native macOS, GPU-accelerated).
# requires: bun, git, and tmux or kitty
npm install -g automuxFor kitty, additional config is needed — see docs/kitty-setup.md.
cd your-project
automux init # scaffold .automaton/ structure
automux start # launch main agent in tmuxThe main agent reads AGENTS.md, understands the workflow, and uses automux commands to spawn subagents.
You run one command (automux start) and watch. The main agent handles orchestration. Subagents appear as panes on the right. You can intervene anytime by typing into any pane.
Main agent (pane 0) orchestrates using automux CLI:
automux spawn login-page coder --provider claude # create subagent
automux send login-page-coder "start implementing" # send instruction
automux capture login-page-coder --lines 10 # quick status check
automux list # see all agents
automux stop login-page-coder # pause agent
automux resume login-page-coder # resume with history
automux remove login-page-coder # cleanupSubagents (right panes) communicate through files only:
.automaton/features/{feature}/brief.md ← main agent writes task
.automaton/features/{feature}/{role}-output.md ← subagent writes result
.automaton/features/{feature}/status.md ← main agent tracks progress
Subagents never touch the terminal backend. They read a brief, write code, commit, and output results to a file.
Human
└── automux start
└── Main Agent (pane 0, main branch)
├── automux spawn → Planner (worktree, own branch)
├── automux spawn → Coder (worktree, own branch)
└── automux spawn → Reviewer (worktree, own branch)
| Layer | Purpose |
|---|---|
| tmux / kitty | Visual — human observes agents in split panes |
| Files | Communication — briefs in, outputs out, no pane scraping |
| SQLite | State — pane IDs, session IDs, agent status |
| Git worktrees | Isolation — each agent gets its own branch |
| automux CLI | Lifecycle — spawn, stop, resume, remove, send, capture |
| Command | Description |
|---|---|
automux init |
Scaffold .automaton/ structure, roles, skills, AGENTS.md |
automux start [--provider X] [--backend tmux|kitty] |
Launch main agent session |
automux spawn <feature> <role> [--provider X] |
Create worktree + pane + agent |
automux list |
Show all tracked agents |
automux send <target> <message> |
Send text to agent pane (bracketed paste) |
automux capture <target> [--lines N] |
Read agent pane output |
automux resume <id> |
Resume a stopped agent with conversation history |
automux stop <id> |
Stop agent (preserves state for resume) |
automux remove <id> |
Stop + delete worktree + clear state |
Target accepts: agent ID (login-page-coder), pane ID (%5), or feature/role format.
Roles define agent behavior. Stored in .automaton/roles/*.md with YAML frontmatter:
---
name: coder
description: Implements features based on plans and briefs
role: developer
---
You are a coder. You implement, you do not design or review.
...Built-in roles:
| Role | Philosophy |
|---|---|
| planner | Designs approach. Reads broadly, writes a plan. Does not implement. |
| coder | Implements code. Follows the plan, stays in scope. Does not review. |
| reviewer | Reviews diffs. Finds flaws, does not fix them. Outputs APPROVE or REVISE. |
Add custom roles by dropping a .md file in .automaton/roles/.
1. Brief → write .automaton/features/{feature}/brief.md
2. Spawn → automux spawn {feature} {role} --provider claude
3. Monitor → read {role}-output.md (fallback: automux capture)
4. Review → read output + git diff main...agent/{feature}/{role}
5. Merge → git merge agent/{feature}/{role}
6. Clean → automux remove {feature}-{role}
your-project/
├── .automaton/
│ ├── roles/ # agent role definitions
│ │ ├── coder.md
│ │ ├── reviewer.md
│ │ └── planner.md
│ ├── skills/ # reusable instruction files
│ │ ├── automux-cli.md
│ │ ├── automux-workflow.md
│ │ └── handoff.md
│ └── features/ # per-feature: brief, outputs, status
│ └── worktrees/ # gitignored, agent worktrees
├── AGENTS.md # main agent instructions (Codex/Gemini)
├── CLAUDE.md → AGENTS.md # symlink for Claude Code
└── .claude/skills → .automaton/skills
- File-based communication — agents write markdown files, not pane output. Saves tokens, prevents parsing errors.
- Bracketed paste (tmux) — input delivery uses
tmux load-buffer+paste-buffer -pwith 300ms delay. Kitty usessend-textvia remote control. - AGENTS.md as source of truth — CLAUDE.md symlinks to it. Works with Claude Code, Codex, and Gemini CLI.
- Git worktrees for isolation — each agent gets its own branch (
agent/{feature}/{role}). No conflicts, real git history. - Session ID persistence — Claude sessions can be resumed with
automux resume. Full conversation history restored. - Main-vertical layout — main agent stays full-height left, subagents stack on the right.
automux is developed using automux. The main agent spawns subagents to write code, review diffs, and plan features — all in worktrees of the automux repo itself. After merging, bun run build updates the global command. The improved tool is immediately available for the next feature.
- Terminal Backends — tmux vs kitty, detection, lifecycle, recovery
- Kitty Setup — configuration, troubleshooting, differences from tmux
- Runtime: Bun
- Language: TypeScript
- State: SQLite via
bun:sqlite - Terminal: tmux or kitty
- Isolation: Git worktrees
MIT