---

name: swarm description: Orchestrate parallel Claude Code worker swarms with protocol-based behavioral governance. Use for complex features, large refactors, or multi-step tasks. Supports behavioral constraints, parallel workers, and persistent state across context compactions.

Claude Swarm Skill

This skill enables autonomous, multi-hour coding sessions using the claude-swarm MCP server with protocol-based behavioral governance.

Overview

The orchestrator pattern separates concerns:

• Orchestrator (you): Plans work, monitors progress, handles decisions
• Workers: Focused Claude Code sessions that implement individual features
• Protocols: Behavioral constraints that govern what workers can/cannot do

Quick Start

1. Initialize a Session

First, analyze the task and decompose it into features:

Task: "Build a user authentication system"

Features:
1. Create user registration endpoint with validation
2. Implement password hashing with bcrypt
3. Add JWT token generation and verification
4. Create login endpoint
5. Add protected route middleware
6. Implement logout and token invalidation

Then initialize:

Use orchestrator_init with:
- projectDir: /path/to/project
- taskDescription: "Build a user authentication system with..."
- existingFeatures: [list of feature descriptions above]

2. Work Loop

IMPORTANT: Workers typically take 5-10 minutes per feature. Do NOT check workers immediately after starting them.

For each pending feature:

1. start_worker for the feature (or start_parallel_workers for independent features)
2. WAIT 2-3 minutes before first check (use: sleep 120 or sleep 180)
3. check_worker to monitor progress
4. If still working, wait another 2-3 minutes before checking again
5. Use send_worker_message if worker needs additional guidance
6. When worker completes, run_verification (tests, build, etc.)
7. mark_complete with success/failure (auto-retry enabled by default)
8. commit_progress to checkpoint
9. Repeat for next feature

For parallel execution:

1. Identify independent features (no dependencies between them)
2. Use set_dependencies if features must be ordered
3. Use validate_workers to check for conflicts before starting
4. start_parallel_workers with multiple feature IDs
5. Run: sleep 180 (wait 3 minutes before checking)
6. Use check_all_workers to monitor all workers at once
7. Mark each complete as they finish

3. After Context Compaction

If your context is compacted, simply:

Call orchestrator_status with the projectDir

This restores your understanding of the current state from the persistent MCP server.

Protocol-Based Governance

Protocols define behavioral constraints that govern worker actions. This enables safe autonomous operation with clear boundaries.

Constraint Types

Type	Description	Example
tool_restriction	Allow/deny specific tools	Only allow Read, Glob, Grep
file_access	Control file system access	Block access to .env files
output_format	Require specific output patterns	Must include test coverage
behavioral	High-level behavior rules	Require confirmation before destructive actions
temporal	Time-based constraints	Max 30 minutes per feature
resource	Resource usage limits	Max 100 file operations
side_effect	Control external effects	No network requests, no git push

Using Protocols

1. protocol_register - Register a new protocol (JSON definition)
2. protocol_activate - Activate for enforcement
3. start_worker - Workers are validated against active protocols
4. get_violations - Review any constraint violations
5. protocol_deactivate - Deactivate when done

Example Protocol

{
  "id": "safe-refactoring-v1",
  "name": "Safe Refactoring Protocol",
  "version": "1.0.0",
  "priority": 100,
  "constraints": [
    {
      "id": "no-secrets",
      "type": "file_access",
      "rule": {
        "type": "file_access",
        "deniedPaths": ["**/.env", "**/secrets.*"]
      },
      "severity": "error",
      "message": "Cannot access files that may contain secrets"
    }
  ],
  "enforcement": {
    "mode": "strict",
    "preExecution": true,
    "postExecution": true,
    "onViolation": "block"
  }
}

LLM-Generated Protocols

Workers can propose new protocols validated against immutable base constraints:

1. get_base_constraints - View immutable security rules
2. propose_protocol - Worker submits proposal
3. review_proposals - See pending proposals with risk scores
4. approve_protocol / reject_protocol - Human review for high-risk

Best Practices

Feature Decomposition

• Each feature should be completable in 15-60 minutes
• Features should be independently testable
• Order features by dependency (foundations first)
• Use set_dependencies to enforce ordering when needed

Parallel Execution

• Identify features that can run in parallel (no shared dependencies)
• Use start_parallel_workers to launch up to 10 workers at once
• Monitor all workers with check_all_workers
• Independent features complete faster when parallelized

Monitoring Workers

• Wait 2-3 minutes after starting before first check
• Use sleep 120 or sleep 180 between starting and checking
• Workers typically complete features in 5-10 minutes
• If stuck after 10+ minutes, review output carefully
• Use send_worker_message to provide guidance without restarting

Efficient Monitoring with Heartbeat Mode

Use check_worker with heartbeat: true for lightweight status checks:

check_worker(featureId, heartbeat: true)
-> Returns: status, lastToolUsed, lastFile, lastActivity, runningFor

Competitive Planning for Complex Features

For complex features (score >= 60), use competitive planning:

1. get_feature_complexity(featureId) - Analyze complexity
2. start_competitive_planning(featureId) - Spawn 2 planners
3. Wait for planners to complete (3-5 minutes)
4. evaluate_plans(featureId) - Compare and pick winner
5. start_worker with the winning plan as context

Confidence-Based Monitoring

Track worker confidence to detect issues early:

1. set_confidence_threshold(35) - Configure alert threshold
2. get_worker_confidence(featureId) - Get detailed breakdown

Confidence levels:

• High (80-100): On track
• Medium (50-79): Normal operation
• Low (25-49): May need guidance
• Critical (0-24): Immediate attention

Post-Completion Reviews

After all workers complete, automated reviews run automatically:

1. All workers complete -> session transitions to "reviewing" status
2. Code review worker analyzes: bugs, security, style, test coverage
3. Architecture review worker analyzes: coupling, patterns, scalability
4. Findings aggregated into progress log
5. Use get_review_results for detailed findings
6. Use implement_review_suggestions to convert findings into new features

Review configuration:

• configure_reviews(enabled: false) - Disable automatic reviews
• run_review(reviewTypes: ["code"]) - Manually run specific reviews

Acting on Review Findings

Convert review issues into actionable features:

# View available issues from reviews
implement_review_suggestions(projectDir)

# Create features from specific issues by index
implement_review_suggestions(projectDir, issueIndices: [0, 2, 5])

# Auto-select warnings and errors
implement_review_suggestions(projectDir, autoSelect: true, minSeverity: "warning")

Error Recovery

• Auto-retry is enabled by default (3 attempts) via mark_complete
• Use retry_feature to manually reset after fixing issues
• Use add_feature if you discover missing work

Session Management

• Use pause_session to gracefully stop work
• Use resume_session to continue where you left off
• Use get_session_stats for success rates and timing

Git Checkpoints

• Commit after each successful feature with commit_progress
• Use descriptive commit messages
• Enables easy rollback if needed

Web Dashboard

A real-time web dashboard is available at http://localhost:3456:

• Live updates via Server-Sent Events
• Session overview with progress bar
• Feature cards with status and dependencies
• Worker terminal output streaming with ANSI color support
• Review worker progress visibility
• Dark mode support

Tools Reference

Core Orchestration

Tool	Purpose
orchestrator_init	Start new session with features
orchestrator_status	Check current state (use after compaction!)
orchestrator_reset	Nuclear option - clear everything

Worker Management

Tool	Purpose
start_worker	Launch worker for a feature
start_parallel_workers	Launch multiple workers
validate_workers	Pre-flight validation
check_worker	Monitor worker output (heartbeat + cursor modes)
check_all_workers	Check all active workers at once
send_worker_message	Send instructions to running worker

Competitive Planning

Tool	Purpose
get_feature_complexity	Analyze complexity score
start_competitive_planning	Spawn 2 planners
evaluate_plans	Compare and select winner

Confidence Monitoring

Tool	Purpose
get_worker_confidence	Get confidence breakdown
set_confidence_threshold	Configure alert threshold

Feature Management

Tool	Purpose
mark_complete	Mark feature done/failed (auto-retry)
retry_feature	Reset for manual retry
run_verification	Run tests/build
add_feature	Add discovered work
set_dependencies	Define dependencies

Session & Progress

Tool	Purpose
get_progress_log	Full history (paginated)
get_session_stats	Success rates and timing
pause_session	Pause, stop all workers
resume_session	Resume paused session
commit_progress	Git checkpoint

Post-Completion Reviews

Tool	Purpose
run_review	Manually trigger reviews
check_reviews	Monitor review worker progress
get_review_results	Get aggregated findings
configure_reviews	Configure automatic reviews
implement_review_suggestions	Convert findings into features

Protocol Management

Tool	Purpose
protocol_register	Register a protocol
protocol_activate	Activate for enforcement
protocol_deactivate	Deactivate protocol
protocol_list	List all protocols
protocol_status	Get protocol status

Protocol Enforcement

Tool	Purpose
validate_feature_protocols	Check feature against protocols
get_violations	Get violations (paginated)
resolve_violation	Mark violation resolved
get_audit_log	Get audit history

LLM Protocol Generation

Tool	Purpose
get_base_constraints	View immutable constraints
propose_protocol	Submit proposal
review_proposals	List pending proposals
approve_protocol	Approve proposal
reject_protocol	Reject proposal

Example Session

User: "Build a REST API for a todo app with CRUD operations"

[Analyze and decompose into features]

Me: I'll orchestrate building this API. Let me initialize the session.

[Call orchestrator_init with features:
1. Set up Express server with basic middleware
2. Create Todo model with Mongoose
3. Implement POST /todos endpoint
4. Implement GET /todos endpoint
5. Implement PUT /todos/:id endpoint
6. Implement DELETE /todos/:id endpoint
7. Add input validation middleware
8. Add error handling middleware
9. Write integration tests]

Session initialized with 9 features.

[start_worker for feature-1]
Worker started: cc-worker-feature-1-abc123

[Run: sleep 180]  # Wait 3 minutes before first check

[check_worker for feature-1]
Worker output shows Express setup complete...

[run_verification: "npm run build"]
Build passed!

[mark_complete: feature-1, success: true]
[commit_progress: "feat: set up Express server"]

Moving to feature-2...
[start_worker for feature-2]
...

[Continue until all features complete]
[Automatic code and architecture reviews run]
[get_review_results to see findings]
[implement_review_suggestions to create follow-up features if needed]

Repo Setup

Use the Repo Setup feature to configure new or existing repositories with development best practices. The swarm can set up CLAUDE.md files, CI/CD workflows, issue templates, and more—all in parallel with smart defaults based on your project type.

When to Use

• Fresh projects: Initialize a new repo with complete development infrastructure
• Adding CI to existing projects: Add GitHub Actions, Dependabot, or Release Please to a mature codebase
• Standardizing repos: Apply consistent configuration across multiple repositories
• Upgrading configs: Update outdated CI workflows or templates to current best practices

Quick Setup Workflow

User: "Set up this new TypeScript project with CI, issue templates, and release automation"

[Analyze project: detect package.json, tsconfig.json, src/ structure]

Me: I'll configure this repo with appropriate settings. Let me initialize the setup swarm.

[Call orchestrator_init with features:
1. Create CLAUDE.md with project-specific guidance
2. Add GitHub Actions CI workflow for TypeScript
3. Configure Dependabot for npm dependencies
4. Add Release Please for automated releases
5. Create issue templates (bug report, feature request)
6. Add pull request template
7. Create CONTRIBUTING.md with guidelines
8. Add SECURITY.md with vulnerability policy]

Session initialized with 8 features.

[start_parallel_workers for features 1-8]  # All independent, run in parallel
Workers started for all configuration features...

[Run: sleep 120]  # Wait 2 minutes

[check_all_workers]
All workers completed successfully.

[run_verification: "npm run build && npm test"]
Build and tests pass with new configuration!

[commit_progress: "chore: add repo configuration and CI"]

Configuration Types

Type	Description	Files Created
CLAUDE.md	Project guidance for Claude Code	CLAUDE.md
GitHub CI	Build, test, lint workflows	.github/workflows/ci.yml
Release Please	Automated version bumps and changelogs	.github/workflows/release-please.yml, .release-please-manifest.json
Dependabot	Automated dependency updates	.github/dependabot.yml
Issue Templates	Structured bug/feature reporting	.github/ISSUE_TEMPLATE/*.yml
PR Template	Consistent pull request descriptions	.github/PULL_REQUEST_TEMPLATE.md
CONTRIBUTING.md	Contribution guidelines	CONTRIBUTING.md
SECURITY.md	Security policy and vulnerability reporting	SECURITY.md

Customization Options

Control which configurations are applied using these options in your task description or worker prompts:

Skip specific configs - Use skipConfigs to exclude certain configuration types:

"Set up CI and issue templates, but skip Release Please and Dependabot"
-> skipConfigs: ["release-please", "dependabot"]

Force overwrite - Use force: true to replace existing configurations:

"Update all CI workflows to latest patterns, replacing existing ones"
-> force: true (overwrites existing .github/workflows/)

Merge mode (default) - Without force, existing configs are preserved and merged:

• Existing CLAUDE.md sections are kept, new guidance is appended
• Workflow files are only created if they don't exist
• Issue templates add to existing templates rather than replacing

Project Type Detection

The setup swarm auto-detects your project type and applies appropriate defaults:

Detected	Configuration Applied
package.json	Node.js CI, npm Dependabot
tsconfig.json	TypeScript build steps, type checking
pyproject.toml	Python CI, pip/poetry Dependabot
Cargo.toml	Rust CI, cargo Dependabot
go.mod	Go CI, go modules Dependabot
.github/ exists	Merge mode by default, preserves existing

Example: Adding CI to Existing Project

User: "Add GitHub Actions CI to this Python project, keep existing issue templates"

[Detect: pyproject.toml, pytest in dependencies, existing .github/ISSUE_TEMPLATE/]

Me: I'll add Python CI while preserving your existing templates.

[Call orchestrator_init with features:
1. Create GitHub Actions CI for Python with pytest
2. Configure Dependabot for pip dependencies
3. Update CLAUDE.md with CI information]

[start_parallel_workers]
...

[Workers complete, merge with existing .github/ structure]
[Existing issue templates preserved, new CI workflow added]

[commit_progress: "ci: add GitHub Actions workflow for Python"]

Troubleshooting

"No active session"

Run orchestrator_status to check state, or orchestrator_init to start fresh.

Worker seems stuck

1. check_worker to see current output
2. Try send_worker_message to give guidance
3. If truly stuck, mark_complete with success=false (will auto-retry)
4. If retries exhausted, use retry_feature to reset

Feature has unmet dependencies

1. Check dependencies with orchestrator_status
2. Complete dependency features first
3. Or use set_dependencies to modify the chain

Lost context after compaction

Call orchestrator_status - the MCP server maintains all state.

Need to pause temporarily

Use pause_session to stop workers, then resume_session when ready.

Need to abort

Use orchestrator_reset with confirm=true to kill all workers and clear state.

Protocol violations blocking work

1. get_violations to see what was violated
2. Fix the issue or resolve_violation if false positive
3. Adjust protocol constraints if too strict