---
name: claude-squad
description: Use when the user wants to launch multiple Claude Code remote control sessions, run a "claude squad", start parallel claude RC instances, manage background claude sessions, or asks about multi-session claude workflows. Covers launching, listing, stopping, and managing named tmux-based Claude Code remote control sessions controllable from the phone app.
user-invokable: true
---

# Claude Squad

Launch 4 concurrent Claude Code **remote control** sessions in named tmux sessions. Each session runs `claude --dangerously-skip-permissions rc`, which starts remote control mode — generating a session URL that can be controlled from the Claude phone app.

## Session Names

Sessions are named `{repo}-{greek}` so they're identifiable across multiple containers on the phone app. The repo name is derived from the container hostname.

| Session | tmux name (example for `service-jlcpcb`) |
|---------|-----------|
| **Alpha** | `service-jlcpcb-alpha` |
| **Beta** | `service-jlcpcb-beta` |
| **Gamma** | `service-jlcpcb-gamma` |
| **Delta** | `service-jlcpcb-delta` |

## Gallia Viewer Management Dashboard

The squad has a full management UI in Gallia Viewer (GV). Navigate to it from the About page ("Claude Squad" card) or the view dropdown.

### Features

- **Live status** — green/yellow/red indicator showing how many sessions are running, auto-refreshes every 5s
- **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
- **Watchdog** — toggle to auto-restart any dead sessions every 15s; shows restart count and recent restart log
- **Start on boot** — checkbox (default ON) that auto-launches the squad when the GV server starts; persisted across server restarts via `/tmp/squad-watchdog.json`
- **Explainer tooltip** — hover the `?` icon to learn why tmux is used and how to connect from the phone app

### Programmatic Access

Switch any connected viewer to the squad dashboard:
```bash
curl -X POST http://127.0.0.1:8771 -H 'Content-Type: application/json' -d '{"action":"show_squad"}'
```

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| "no server running" from tmux | tmux server not started. The first `new-session` creates it. Run the launch commands again. |
| Session exits immediately | Claude binary not found or crashed. Check `CLAUDE_BIN` path exists. Try running it manually first. |
| "duplicate session" error | Old sessions still running. Kill them first with the stop commands. |
| RC URL not showing | Session may still be initializing. Wait longer and re-capture pane output. |
| "unknown option" error | Make sure the command is `rc` (not `--rc`). The full command is `claude --dangerously-skip-permissions rc`. |
| "Workspace not trusted" | Run `node ~/gallia/install.mjs` to auto-configure trust in `~/.claude.json`, then retry. |
| "Cannot be launched inside another Claude Code session" | The `CLAUDECODE` env var is set. All launch commands use `unset CLAUDECODE;` prefix — make sure it's included. |
| Phone prompts allow/deny for every action | Run `node ~/gallia/install.mjs` to set full bypass permissions in `~/.claude/settings.json`. |