Ep 9: Multi-Agent Parallelism in Action — Terminal Selection Guide for AI Agent Era

Running 5 Agents simultaneously—comparing cmux vs. tmux solutions with detailed Mermaid workflow diagrams.

Scenario

Running 5 Claude Code Agents concurrently:

Agent	Task	Estimated Duration
Agent 1	Phase 1: Calculation Engine	30 min
Agent 2	Phase 2: UI Layer	25 min
Agent 3	Test Runner	Continuous
Agent 4	Code Review	As needed
Agent 5	Bug Debugging	Uncertain

Option A: cmux (Local macOS)

sequenceDiagram
    participant User as Developer
    participant Cmux as cmux
    participant A1 as Agent 1
Phase 1
    participant A2 as Agent 2
Phase 2
    participant A3 as Agent 3
Tests
    participant A4 as Agent 4
Review
    participant A5 as Agent 5
Debug

    rect rgb(230, 245, 255)
    Note over User,A5: Startup Phase
    User->>Cmux: Script starts 5 tabs
    Cmux->>A1: claude /gsd-execute-phase 1
    Cmux->>A2: claude /gsd-execute-phase 2
    Cmux->>A3: claude /gsd-add-tests
    Cmux->>A4: claude /gsd-code-review
    Cmux->>A5: claude /gsd-debug
    end

    rect rgb(255, 245, 230)
    Note over User,A5: Running Phase
    A1->>A1: Executing...
    A2->>A2: Executing...
    A3->>A3: Running tests...

    A1->>Cmux: ⏸ Needs User Decision
    Cmux->>User: 🔔 Ring flashes + Desktop alert
    User->>A1: Input decision
    end

    rect rgb(230, 255, 230)
    Note over User,A5: Completion Phase
    A3->>Cmux: ✅ All tests passed
    Cmux->>User: 🔔 Completion notification
    A4->>Cmux: 📝 Review report generated
    Cmux->>User: 🔔 Report ready
    end

Practical Steps:

Start cmux and use a script to create 5 tabs:

# start_agents.py
import socket, json

def cmux_cmd(cmd):
    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
    sock.connect('/tmp/cmux.sock')
    sock.send(json.dumps(cmd).encode())
    sock.close()

agents = [
    ("agent-phase1", "claude"),
    ("agent-phase2", "claude"),
    ("agent-tests", "claude"),
    ("agent-review", "claude"),
    ("agent-debug", "claude"),
]

for name, cmd in agents:
    cmux_cmd({"action": "new_tab", "name": name, "command": cmd})

Wait for ring notifications and intervene as needed.

Advantage: The notification ring automatically filters your attention, only alerting you when an Agent truly needs you.

Option B: tmux (Local/Remote Universal)

sequenceDiagram
    participant User as Developer
    participant Tmux as tmux
    participant S1 as Session: phase1
    participant S2 as Session: phase2
    participant S3 as Session: tests
    participant S4 as Session: review
    participant S5 as Session: debug

    rect rgb(230, 245, 255)
    Note over User,S5: Startup Phase
    User->>Tmux: Run startup script
    Tmux->>S1: tmux new -s phase1
    S1->>S1: claude /gsd-execute-phase 1
    Tmux->>S2: tmux new -s phase2
    S2->>S2: claude /gsd-execute-phase 2
    Tmux->>S3: tmux new -s tests
    S3->>S3: claude /gsd-add-tests
    Tmux->>S4: tmux new -s review
    S4->>S4: claude /gsd-code-review
    Tmux->>S5: tmux new -s debug
    S5->>S5: claude /gsd-debug
    end

    rect rgb(255, 245, 230)
    Note over User,S5: Monitoring Phase
    User->>Tmux: tmux ls
    Tmux->>User: List 5 sessions
    User->>Tmux: tmux attach -t phase1
    Note over User: Manually check status
    User->>Tmux: Ctrl+b d (detach)
    User->>Tmux: tmux attach -t phase2
    end

    rect rgb(230, 255, 230)
    Note over User,S5: Persistence
    User->>Tmux: Close terminal
    Note over Tmux: 5 sessions keep running
    User->>Tmux: Next day 'tmux attach'
    Note over User: Restore all sessions
    end

Practical Steps:

Batch startup script:

#!/bin/bash
sessions=("phase1" "phase2" "tests" "review" "debug")
for s in "${sessions[@]}"; do
    tmux new-session -d -s "$s" "claude"
done

Monitoring and Restoration: Use tmux ls to view and tmux attach -t <name> to connect.

Advantage: Works on all platforms; supports detach/attach so Agents don't stop when the terminal is closed.

Option C: Hybrid cmux + tmux

graph TB
    subgraph Local macOS
        CMUX[cmux
5 Vertical Tabs]
        CMUX --> |Tab 1| A1[Agent: Phase 1]
        CMUX --> |Tab 2| A2[Agent: Phase 2]
        CMUX --> |Tab 3| SSH[SSH → Remote Server]
    end

    subgraph Remote Linux
        TMUX[tmux
3 Sessions]
        TMUX --> S1[Agent: Review]
        TMUX --> S2[Agent: Debug]
    end

    SSH --> TMUX

Local cmux manages Agents on macOS, while tmux handles Agents on remote servers via SSH. The two systems complement each other perfectly.