Swarm Orchestrator

---

name: swarm-orchestrator description: Split a large task across multiple parallel Claude Code worker agents running in tmux panes inside the same terminal window (or as background processes when tmux is unavailable), orchestrated by the current session as master. Use when the user explicitly asks to "split this into N agents", "use agents", "run with swarm", "parallelize this", or when a task naturally decomposes into 2 or more independent subtasks that can run concurrently.

Swarm Orchestrator

You are the master agent. You split work, spawn workers, assign each worker a model sized to its task, track progress, and merge results. Workers are separate claude sessions that do the actual work.

When to activate

• Explicit trigger: the user asks to split work into N agents, use a swarm, or parallelize.
• Automatic trigger: the task decomposes into 2+ subtasks that are truly independent (no shared files, no ordering between them). If subtasks depend on each other, do NOT swarm; run them yourself sequentially.

Choose worker count by counting genuinely independent subtasks. Default to 2-4 workers. Never split beyond the number of real independent subtasks, and never spawn more than 8 workers.

Step 1: detect the environment

Run:

bash "${CLAUDE_PLUGIN_ROOT}/scripts/detect-env.sh"

This checks the OS, tmux, WSL (on Windows), git, gh, and the claude CLI, auto-installs tmux where possible (brew on macOS, apt/dnf/pacman on Linux, apt inside WSL), and writes the chosen mode to .claude-swarm/env:

• mode: tmux - full split-panes mode. Each worker is an interactive claude session in its own tmux pane, all visible at once.
• mode: in-process - fallback. Workers run as headless background claude -p processes, output goes to .claude-swarm/logs/worker-N.log.

If the script prints notes (for example, Windows without WSL), relay them to the user verbatim, including the WSL install link. Never try to install WSL yourself.

Step 2: plan the split and assign models

Break the task into one clear, self-contained assignment per worker. Each assignment must include full context: which files/areas the worker owns, what done means, and what it must not touch (to avoid conflicts with other workers).

Assign each worker a model by the size of its task:

Task size	Model	Examples
Small, mechanical	haiku	renames, boilerplate, docs, simple config, trivial tests
Standard	sonnet	a feature in a few files, a bugfix that needs investigation, tests for a module
Large, complex	opus	cross-cutting refactors, architecture changes, hard debugging

Default to sonnet when unsure. Tell the user which model each worker got and why.

Step 3: spawn workers

bash "${CLAUDE_PLUGIN_ROOT}/scripts/spawn-workers.sh" 3 --models haiku,sonnet,opus

The Nth entry in --models is worker N's model. In tmux mode this kills any stale claude-swarm session first, then opens N tiled panes each running claude --model <assigned>. In in-process mode it prepares log/status files and stores each worker's model for send-task.

Step 4: send tasks

One call per worker, with the full assignment as a single-line prompt:

bash "${CLAUDE_PLUGIN_ROOT}/scripts/send-task.sh" 0 "You are worker 0 of 3. Your task: ... Only touch src/auth/. When finished, print exactly: WORKER 0 DONE"

Always end each prompt with an instruction to print a unique completion marker (WORKER N DONE), so status collection can detect completion.

Details per mode:

• tmux: the prompt is typed into the pane with send-keys -l (literal mode), then after a short delay a separate Enter keypress submits it. The delay avoids a race where Enter arrives before the text. Newlines in the prompt are flattened to spaces.
• in-process: the script launches claude -p --model <assigned> "<prompt>" in the background and refuses to send a new task while the worker's previous task is still running. You can override the model per task with --model.

Step 5: monitor

Poll every 30-60 seconds:

bash "${CLAUDE_PLUGIN_ROOT}/scripts/collect-status.sh"

Shows the last lines of every worker (tmux capture-pane or the log file) plus run status in in-process mode. Pass a worker index to inspect just one. After each poll, give the user a one-line status per worker. A worker is finished when its output contains its WORKER N DONE marker (or its status file reads done/failed).

If a worker is stuck or failed, send it a follow-up task with send-task.sh, or take over its subtask yourself.

Step 6: integrate and clean up

When all workers are done: review their output, verify the combined result actually works (run builds/tests as appropriate), fix integration gaps yourself, and summarize per worker what was accomplished. Then:

bash "${CLAUDE_PLUGIN_ROOT}/scripts/teardown.sh"

Add --purge to also delete the .claude-swarm/ state directory.

Rules

• Never give two workers overlapping file ownership.
• Keep prompts self-contained; workers share no conversation state with you or each other.
• Add .claude-swarm/ to the project's .gitignore (or .git/info/exclude) if it is not already ignored.
• Update the user in real time: what each worker is doing, which model it uses, and current status.