Claude Squad launches 4 concurrent Claude Code remote control sessions in named tmux sessions (alpha, beta, gamma, delta). Each session runs claude --dangerously-skip-permissions rc, generating a session URL controllable from the Claude phone app.
Why tmux?
tmux provides persistent terminal sessions that survive disconnects. Each Claude RC session runs inside its own tmux session, which means:
- Sessions persist even if you close your browser or lose connection
- Output can be captured programmatically (
tmux capture-pane) for monitoring - Sessions can be controlled by sending keystrokes (
tmux send-keys) - Multiple sessions coexist independently without interfering with each other
Architecture
┌─────────────────────────────────────────────────┐
│ Adom Container │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ │ tmux │ │ tmux │ │ tmux │ │ tmux │
│ │ alpha │ │ beta │ │ gamma │ │ delta │
│ │ │ │ │ │ │ │ │
│ │ claude │ │ claude │ │ claude │ │ claude │
│ │ --skip │ │ --skip │ │ --skip │ │ --skip │
│ │ rc │ │ rc │ │ rc │ │ rc │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │ │ │
│ └──────────────┴──────┬───────┴──────────────┘
│ │
│ ┌──────────────────────────┴───────────────────┐
│ │ Gallia Viewer (GV) │
│ │ - Live status dashboard │
│ │ - Start / Restart / Stop controls │
│ │ - Watchdog auto-restart (15s interval) │
│ │ - Per-session chat output viewer │
│ │ - Auto-start on boot │
│ └───────────────────────────────────────────────┘
│ │
└─────────────────────────────┼───────────────────┘
│
┌─────────┴─────────┐
│ Claude Phone App │
│ (Remote Control) │
└───────────────────┘
Gallia Viewer Dashboard
The squad has a full management UI built into Gallia Viewer. Features include:
- Live status — green/yellow/red indicator showing how many sessions are running, auto-refreshes every 5 seconds
- Start / Restart / Stop — buttons to launch all 4 sessions, restart the entire squad, or stop everything
- Per-session restart — click the restart icon on any card to restart just that session
- Chat output — click a session card to view its full tmux pane output (last 1000 lines), auto-scrolls to bottom
- Watchdog — toggle to auto-restart any dead sessions every 15 seconds; shows restart count and recent restart log
- Start on boot — checkbox (default ON) that auto-launches the squad when the GV server starts
- Explainer tooltip — hover the
?icon for a quick overview of why tmux is used
Phone App Experience
On the Claude phone app, each RC session appears as "Remote Control session" with the container ID. Currently the Claude CLI rc subcommand doesn't support custom session naming, so all 4 sessions look identical on the phone — differentiated only by their start timestamp. The GV dashboard compensates by clearly labeling each channel (Alpha, Beta, Gamma, Delta) with color-coded badges.
Session Naming
Sessions use the pattern {repo}-{greek}:
| Session | Example tmux name |
|---|---|
| Alpha | gallia-alpha |
| Beta | gallia-beta |
| Gamma | gallia-gamma |
| Delta | gallia-delta |
The repo name is derived from the container's VSCODE_PROXY_URI environment variable.
Commands
| Action | How |
|---|---|
| Launch squad | /claude-squad or click "Start Squad" in GV |
| Check status | GV dashboard (auto-refreshes) or tmux list-sessions |
| Stop all | Click "Stop Squad" in GV |
| Restart one | Click restart icon on individual card in GV |
| Send prompt | tmux send-keys -t {repo}-alpha "your prompt" Enter |
| View output | Click a session card in GV, or tmux capture-pane -t {repo}-alpha -p -S -500 |
| Enable watchdog | Toggle switch in GV dashboard |
Capabilities
- Launch 4 concurrent Claude Code RC sessions in one click
- Monitor session status with color-coded cards (green = running, red = dead)
- View live chat output from any session
- Auto-restart dead sessions with built-in watchdog (15-second check interval)
- Auto-launch squad on container boot (configurable)
- Restart individual sessions without affecting others
- Send prompts to sessions via tmux
- Full programmatic API via WebSocket and HTTP