██████╗███████╗██╗ ██╗ █████╗ ██████╗ ███╗ ███╗
██╔════╝██╔════╝██║ ██║██╔══██╗██╔══██╗████╗ ████║
██║ ███████╗██║ █╗ ██║███████║██████╔╝██╔████╔██║
██║ ╚════██║██║███╗██║██╔══██║██╔══██╗██║╚██╔╝██║
╚██████╗███████║╚███╔███╔╝██║ ██║██║ ██║██║ ╚═╝ ██║
╚═════╝╚══════╝ ╚══╝╚══╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝
parallel claude code agents, orchestrated through slash commands.
one /swarm-init, one /swarm-launch, walk away. come back to merged branches.
┌─────────────────────────────────────────────────────────────────┐
│ │
│ you> /swarm-init "Build auth, dashboard, and API" │
│ Claude analyzes codebase, proposes 3 tasks │
│ │
│ you> /swarm-spec │
│ Claude writes detailed specs per task │
│ │
│ you> /swarm-launch │
│ ┌───────────┬───────────┬───────────┐ │
│ │ worker 1 │ worker 2 │ worker 3 │ <- tmux panes │
│ │ auth-ui │ dashboard │ api-crud │ │
│ │ done │ working │ working │ │
│ └───────────┴───────────┴───────────┘ │
│ each worker: own git branch + own worktree │
│ ralph loop keeps them going until done │
│ │
│ you> /swarm-status <- check progress anytime │
│ you> /swarm-merge <- merge completed branches │
│ you> /swarm-test <- QA in the browser │
│ you> /swarm-commit <- structured commit message, push │
│ │
└─────────────────────────────────────────────────────────────────┘
each worker is an isolated Claude Code instance running in its own git worktree on its own branch. workers follow a spec, commit incrementally, and signal when done. a ralph wiggum stop hook re-injects the mission prompt each time a worker tries to stop before finishing.
┌──────────────────────────────────────────────────────┐
│ │
│ $ claude plugin marketplace add DDX1/cswarm │
│ $ claude plugin install cswarm │
│ │
└──────────────────────────────────────────────────────┘
commands, skills, and hooks load automatically. start a new session for ~/.cswarm to be configured.
$ git clone https://github.com/DDX1/cswarm.git ~/.cswarm && ~/.cswarm/install.shor from a local clone:
$ git clone https://github.com/DDX1/cswarm.git ~/projects/cswarm
$ ~/projects/cswarm/install.shthe installer previews what it will do, asks once, then symlinks into ~/.claude/. existing files are backed up. updates are just git pull.
platform macOS or Linux (Windows requires WSL)
git xcode-select --install (macOS) / apt install git
tmux brew install tmux (macOS) / apt install tmux
claude npm install -g @anthropic-ai/claude-code
/swarm-init "mission" analyze project, propose tasks, create .swarm/
/swarm-spec [task] deep-dive codebase, generate per-worker specs
/swarm-launch create worktrees + tmux, start claude in each pane
/swarm-status report status: done / working / blocked / stalled
/swarm-merge review diffs, merge completed branches one-by-one
/swarm-stop kill tmux session, preserve worker branches
/swarm-test spawn QA agent to verify merged features e2e
/swarm-commit generate structured commit for all swarm work
commit-msg skill /commit — structured git commits
$ ln -sfn ~/.cswarm/skills/commit-msg ~/.claude/skills/commit-msg
COMMANDS.md full command reference
$ cat ~/.cswarm/config/COMMANDS.md
# open any project in claude code
$ cd ~/my-project && claude
# define the mission
> /swarm-init "Build user auth, admin dashboard, and REST API"
# generate detailed specs
> /swarm-spec
# launch — workers start automatically
> /swarm-launch
# watch workers in real time
$ tmux attach -t swarm
# ctrl+b arrows switch panes
# ctrl+b z zoom one pane
# ctrl+b d detach (swarm keeps running)
# check progress without attaching
> /swarm-status
# merge completed branches
> /swarm-merge
# test everything
> /swarm-test
# generate structured commit
> /swarm-commit
# stop workers if still running
> /swarm-stop /swarm-init ──> task breakdown ──> /swarm-spec ──> spec files
│
/swarm-launch
│
┌──────────────┼──────────────┐
│ │ │
worker 1 worker 2 worker n
claude+ralph claude+ralph claude+ralph
│ │ │
worker/task-1 worker/task-2 worker/task-n
│ │ │
└──────────────┼──────────────┘
│
/swarm-merge
│
/swarm-test
│
/swarm-commit
git worktrees — each worker gets its own copy of the repo via
git worktree add. they share the same.gitbut operate in isolated directories. no worker can interfere with another.
ralph loop — when claude tries to stop before completing its task, the stop hook intercepts and re-injects the mission prompt. the worker sees its own previous commits and continues iterating. exits only when the completion signal is found.
spec-driven workers — each worker reads a precise spec with explicit scope (files to create, modify, read, never touch). prevents scope creep and file conflicts.
completion signals — workers signal done by writing to
.claude/.worker-doneand outputting<promise>TASK_SLUG_COMPLETE</promise>. the stop hook checks for this before allowing claude to exit.
workers are fully isolated at runtime — no shared context, no communication, no side effects.
┌─────────────────────────────────────────────────────────────┐
│ worker 1 (auth) worker 2 (dashboard) │
│ ├── own git worktree ├── own git worktree │
│ ├── own branch ├── own branch │
│ ├── own Claude instance ├── own Claude instance │
│ ├── own .claude/ state ├── own .claude/ state │
│ └── cannot see worker 2 └── cannot see worker 1 │
└─────────────────────────────────────────────────────────────┘
what each worker gets at launch (copies, not shared refs):
PROMPT.md task-specific mission prompt
AGENT.md project context (stack, conventions, structure)
.swarm-specs/*.md all specs (read-only reference)
full project files from the base branch via git worktree
what workers cannot see:
- other workers' commits (different branches, different worktrees)
- other workers' file changes
- other workers' progress or status
how conflicts are prevented:
- each spec declares its file scope: files to create, modify, read, never touch
/swarm-specvalidates that no two workers modify the same file- if scopes overlap, you get merge conflicts during
/swarm-merge— redesign the task breakdown
coordination is spec-based, not runtime. workers discover each other's results only after /swarm-merge integrates branches back.
cswarm/
├── .claude-plugin/ plugin manifest + marketplace config
├── commands/ 8 slash commands (.md files)
├── scripts/ 5 bash orchestration scripts
├── templates/ 4 worker configuration templates
├── hooks/ SessionStart hook (plugin mode)
├── skills/ commit-msg skill
├── config/ COMMANDS.md reference, CLAUDE.md example
├── docs/ architecture, customization, troubleshooting
├── install.sh manual installer (symlinks into ~/.claude/)
└── uninstall.sh clean removal
plugin install — commands, skills, and hooks load automatically from the plugin cache. a ~/.cswarm symlink is created on first session for script/template access.
manual install:
commands/swarm-*.md -> ~/.claude/commands/ one symlink per file
repo root -> ~/.cswarm primary path for scripts + templates
# update
$ cd ~/.cswarm && git pull
# verify
$ ~/.cswarm/install.sh --check
# uninstall
$ ~/.cswarm/install.sh --uninstallsymlinks point to the repo — changes take effect immediately. uninstall removes all symlinks, offers to restore backups, leaves project .swarm/ directories untouched.
commands are markdown files — edit them to change behavior. templates control how worker prompts are generated. see docs/customization.md.
tmux won't start check tmux is installed, kill stale sessions:
$ tmux kill-session -t swarm
workers stop instantly ralph stop hook must be configured — check:
$ cat ~/.cswarm/templates/worker-settings.json
merge conflicts expected when workers touch same files.
redesign task breakdown for better isolation.
see docs/troubleshooting.md for full diagnostics.
macOS ✓ fully supported
Linux ✓ fully supported
Windows ✗ requires WSL (Windows Subsystem for Linux)
cswarm depends on bash, tmux, and symlinks — none are available natively on Windows. install and run inside WSL and everything works unchanged.
- ralph wiggum technique — geoffrey huntley
- claude code — anthropic
- ralphy — michael shimeles