launch-swarm: Claude Code skill wrapping Alastair Thomson's TMUX Swarm launcher (https://github.com/AlastairThomson/Medium)

launch-swarm-gist.md

Wrapper skill for the TMUX Swarm toolkit by Alastair Thomson. Original repo: https://github.com/AlastairThomson/Medium

---

name: launch-swarm description: Launch a multi-agent dev team in tmux with git worktrees and per-role personas. Use when the user says "launch swarm", "launch dev team", "spin up agents", "tmux swarm", "start a multi-agent team", or otherwise asks to orchestrate several Claude/Gemini/Codex agents working in parallel worktrees. Wraps scripts/launch-dev-team.sh.

Launch Swarm

Conversational wrapper around scripts/launch-dev-team.sh — a bash script that provisions a multi-agent development team using git worktrees + tmux, with role-scoped sandboxes and per-agent persona files.

When to trigger

Activate on phrases like:

• "launch the swarm", "launch dev team", "spin up the team"
• "start a tmux swarm", "kick off multi-agent session"
• "set up architect + developers on "
• "tear down the swarm" / "cleanup worktrees" (→ --ForceCleanup)

What the script does

For each role the user supplies, it:

1. Creates a git worktree under <project>/.worktrees/<role>/
2. Copies the chosen persona markdown into the worktree as CLAUDE.md
3. Copies any --Guidance= files into .swarm/Guidance/
4. Opens a tmux window running the chosen CLI (claude, gemini, or codex) with a role-appropriate sandbox

Supported roles: Architect, Developer (repeatable), UX, Security, Cloud, QA, Requirements, DevOps, DataScience, CodeReviewer.

Argument format per role: --Role=<agent>[:<model>]@<persona_markdown_path>

Interactive flow

Never just run the script. Walk the user through these steps:

1. Project directory

Ask for the absolute path (or confirm the current working dir). The script requires a git repo.

2. Roles + agents

Ask which roles they want. For each role, collect:

• Agent CLI: claude | gemini | codex
• Model (optional): e.g. opus-4-6, sonnet-4-5, gemini-2.0-flash-exp, gpt-4
• Persona file: defaults are bundled in assets/personas/ under this skill dir (~/.claude/skills/launch-swarm/assets/personas/). Map roles to the default unless the user overrides:

Role	Default persona
Architect	assets/personas/TMUX_ARCHITECT_MANAGER.md
Developer	assets/personas/TMUX_DEVELOPER.md
UX	assets/personas/TMUX_UX_EXPERT.md
Security	assets/personas/TMUX_SECURITY_EXPERT.md
Cloud	assets/personas/TMUX_CLOUD_EXPERT.md
QA	assets/personas/TMUX_QA_ENGINEER.md

No default personas exist yet for Requirements, DevOps, DataScience, CodeReviewer — ask the user for a path or offer to scaffold one in assets/personas/.

3. Guidance (optional)

Default guidance is bundled in assets/guidance/:

• TMUX_TEAM.md — team coordination conventions
• ARCHITECTURE_GUIDELINES.md — architecture rules
• WORKING_METHODS.md — working methods / process

Default to attaching all three via --Guidance=... unless the user opts out or supplies alternates.

4. Flags

Confirm optional behavior:

• --continue — resume each agent's previous session
• --use-ccr — route Claude agents through claude-code-router
• --ForceCleanup — destructive: removes all worktrees + branches, then exits

5. Preview the command

Show the assembled command BEFORE executing. Example:

SKILL=$HOME/.claude/skills/launch-swarm
$SKILL/scripts/launch-dev-team.sh \
  --Guidance=$SKILL/assets/guidance/TMUX_TEAM.md \
  --Guidance=$SKILL/assets/guidance/ARCHITECTURE_GUIDELINES.md \
  --Guidance=$SKILL/assets/guidance/WORKING_METHODS.md \
  --Architect=claude:sonnet-4-5@$SKILL/assets/personas/TMUX_ARCHITECT_MANAGER.md \
  --Developer=claude:opus-4-6@$SKILL/assets/personas/TMUX_DEVELOPER.md \
  --QA=claude@$SKILL/assets/personas/TMUX_QA_ENGINEER.md \
  ~/Development/myapp

Ask for explicit approval. --ForceCleanup is destructive — require an extra confirmation per ~/.dotfiles/claude/rules/destructive-commands.md.

6. Run it

Execute via the Bash tool. The script is at ~/.claude/skills/launch-swarm/scripts/launch-dev-team.sh. After launch, tell the user how to attach: tmux attach -t <session-name> (session name is printed by the script).

Role sandbox cheatsheet

Role	Scope	Network
Architect	Full project, all tools	Yes
Developer	Own worktree	No
UX	Own worktree	Yes
Security	Own worktree + read main	No
Cloud	Own worktree + aws/tf/docker	Yes
QA	Own worktree + read main	No
Requirements	Read-only main	Yes
DevOps	Own worktree + CI/k8s	Yes
DataScience	Own worktree + python/jupyter	Yes
CodeReviewer	Read-only all worktrees	No

Common recipes

Solo Claude architect + 2 devs, Gemini frontend:

--Architect=claude:sonnet-4-5@personas/architect.md
--Developer=claude:opus-4-6@personas/backend.md
--Developer=gemini:gemini-2.0-flash-exp@personas/frontend.md

Review-only pass:

--CodeReviewer=claude:opus-4-6@personas/reviewer.md
--Security=claude@personas/security.md

Teardown:

scripts/launch-dev-team.sh --ForceCleanup ~/Development/myapp

Notes

• Canonical personas live in ~/.claude/tmux_personas/, guidance in ~/.claude/tmux_guidance/. Prefer these over ad-hoc paths.
• The script uses set -e; surface any failure to the user rather than continuing.
• Do not modify the script mid-flow. File issues/requests separately.