tmux-multi-agent

name: tmux-multi-agent description: Multi-pane tmux layouts for coordinating multiple Claude Code agents

Multi-Agent Orchestration

Overview

Run multiple Claude Code instances in a single tmux session, each in its own pane. Panes are addressed by index (0, 1, 2, ...) and can receive independent tasks.

Quick Start

# Create a 3-agent swarm
scripts/multi-agent-setup.sh my-swarm --agents 3 --workdir ~/project

# Send tasks to each agent
scripts/send-message.sh my-swarm --pane 0 "implement the database models"
scripts/send-message.sh my-swarm --pane 1 "implement the API routes"
scripts/send-message.sh my-swarm --pane 2 "write the test suite"

# Monitor progress
scripts/multi-agent-dashboard.sh my-swarm --watch 10

Setup Options

Basic (shell panes)

scripts/multi-agent-setup.sh my-swarm --agents 3 --workdir ~/project
# Creates 3 bash panes. Send Claude commands manually.

With Claude Code pre-started

scripts/multi-agent-setup.sh my-swarm --agents 3 --workdir ~/project --claude
# Each pane starts an interactive Claude Code session.

With specific model

scripts/multi-agent-setup.sh my-swarm --agents 3 --workdir ~/project --claude --model opus

With pre-defined tasks

Create a tasks JSON file:

[
  {"pane": 0, "task": "implement user authentication"},
  {"pane": 1, "task": "write API integration tests"},
  {"pane": 2, "task": "set up CI/CD pipeline"}
]

scripts/multi-agent-setup.sh my-swarm --agents 3 --workdir ~/project --tasks tasks.json

Layout Options

scripts/multi-agent-setup.sh my-swarm --agents 4 --layout main-vertical --workdir ~/project

See references/multi-pane-layouts.md for ASCII diagrams of each layout.

Monitoring

Dashboard

# One-shot status
scripts/multi-agent-dashboard.sh my-swarm

# Auto-refresh every 5 seconds
scripts/multi-agent-dashboard.sh my-swarm --watch 5

# JSON output (for programmatic monitoring)
scripts/multi-agent-dashboard.sh my-swarm --json

Status indicators:

• [*] WORKING - Agent is actively processing
• [!] ERROR - Error detected in output
• [?] WAITING - Agent is waiting for input/approval
• [+] DONE - Agent reports completion
• [-] IDLE - Agent appears idle (at shell prompt)

Tail a specific pane

# One-shot capture
scripts/pane-tail.sh my-swarm --pane 1 --lines 30

# Continuous follow
scripts/pane-tail.sh my-swarm --pane 1 --follow 3

Coordination Patterns

Fan-out / Fan-in

Distribute tasks, then collect results:

# Fan out
scripts/send-message.sh my-swarm --pane 0 "implement feature A"
scripts/send-message.sh my-swarm --pane 1 "implement feature B"
scripts/send-message.sh my-swarm --pane 2 "implement feature C"

# Wait and collect
sleep 120
for i in 0 1 2; do
  echo "=== Pane $i ==="
  scripts/session-review.sh my-swarm --pane "$i" --lines 20
done

Lead/Worker

Pane 0 is the lead, others are workers:

scripts/multi-agent-setup.sh my-swarm --agents 4 --layout main-vertical --workdir ~/project

# Lead agent plans
scripts/send-message.sh my-swarm --pane 0 "analyze the codebase and create a plan"

# Wait for plan
sleep 60
PLAN=$(scripts/session-review.sh my-swarm --pane 0 --lines 50)

# Assign work based on plan
scripts/send-message.sh my-swarm --pane 1 "implement: step 1 from the plan"
scripts/send-message.sh my-swarm --pane 2 "implement: step 2 from the plan"
scripts/send-message.sh my-swarm --pane 3 "implement: step 3 from the plan"

Pipeline

Sequential processing where output feeds forward:

# Stage 1: Generate
scripts/send-message.sh my-swarm --pane 0 "generate the API schema"
sleep 60

# Stage 2: Implement (based on stage 1)
OUTPUT=$(scripts/session-review.sh my-swarm --pane 0 --lines 100)
echo "Implement this schema: $OUTPUT" | scripts/send-message.sh my-swarm --pane 1 --stdin
sleep 60

# Stage 3: Test (based on stage 2)
scripts/send-message.sh my-swarm --pane 2 "write tests for the newly implemented API"

Limits

• Max 8 panes recommended: Beyond 8, panes become too small to read and tmux performance degrades
• Memory: Each Claude Code instance uses its own context window. 4 agents = 4x memory
• Disk: Each agent writes to the same working directory. Coordinate to avoid file conflicts

Cleanup

# Kill the entire swarm
scripts/cleanup.sh my-swarm

# Or kill session directly
scripts/session-kill.sh my-swarm --force