skill

Claude Squad

Unreviewed

by Kyle Bergstedt

Launch and manage 4 concurrent Claude Code remote control sessions via tmux. Includes a Gallia Viewer management dashboard with live status, start/restart/stop controls, watchdog auto-restart, and aut

Overview Files Versions Dependencies Discussions Activity
claude-squad / SKILL.md
Raw

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:

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.