What it does

Runs multiple AI agents in parallel using tmux panes as isolated terminal contexts. Each agent gets its own pane, its own working directory, and its own process. An orchestrator monitors all of them without interrupting their work.

The pattern

Create a tmux session with a grid layout sized to your workload:

• 4-pane grid for parallel independent agents (each working on a separate task)
• 2-pane split for paired work (one agent writes, another reviews)
• 6-pane grid for larger orchestration (multiple workers plus a coordinator pane)

Each pane runs a headless AI agent process. The orchestrator (you or a coordinator agent) manages work distribution and monitors progress.

Key technique: tmux capture-pane. This command reads the current visible content of any pane without sending keystrokes or interrupting the running process. Use it to check agent progress, detect errors, or confirm completion. The agent never knows you looked.

Status file coordination. Agents write their status to shared files (e.g., /tmp/agent-1-status.txt). The orchestrator reads these files to track progress. This avoids the fragility of parsing terminal output and gives you structured data to work with.

The workflow:

1. Create tmux session with named panes
2. Send agent launch commands to each pane via tmux send-keys
3. Poll status files or capture pane content at intervals
4. When an agent finishes, send it the next task or tear down its pane
5. Collect outputs and merge results

Key decisions

tmux over background processes. Background processes lose their terminal context and make debugging painful. tmux preserves the full terminal state, lets you attach for debugging, and survives SSH disconnections.

Status files over pipe-based IPC. Files are simple, inspectable, and resilient. Named pipes and sockets add complexity that is rarely justified for agent coordination.

Named panes. Use tmux select-pane -T "worker-1" to name panes. When you have 4+ agents, positional references ("top-left pane") break down fast.

Non-blocking monitoring. tmux capture-pane -p -t session:window.pane prints pane content to stdout. Wrap it in a polling loop with sleep intervals. Never send keystrokes to a pane just to check status.

When to use it

When you need multiple AI agents running simultaneously with their own terminal contexts. Common scenarios: running parallel code generation tasks, executing test suites while building features, or orchestrating multi-step workflows where each step is handled by a different agent. Not worth the setup for sequential single-agent work.