Claude Swarm

An MCP server for orchestrating parallel Claude Code worker swarms with protocol-based behavioral governance. Enables multi-hour autonomous coding sessions with persistent state, parallel workers, and runtime enforcement of behavioral constraints.

Features

Worker Orchestration

• Persistent State - Session state survives context compaction via MCP server
• Parallel Workers - Run multiple Claude Code workers simultaneously via tmux
• Competitive Planning - Complex features get two competing implementation plans
• Confidence Monitoring - Multi-signal scoring detects struggling workers
• Auto-retry - Failed features automatically retry with configurable limits
• Feature Dependencies - Define execution order between features
• Post-Completion Reviews - Automated code and architecture reviews with actionable findings

Protocol-Based Governance

• Behavioral Protocols - Define constraints on what workers can/cannot do
• Pre-spawn Validation - Verify protocols allow task before worker starts
• Continuous Monitoring - Track constraint violations during execution
• LLM-Generated Protocols - Workers can propose new protocols (validated against base constraints)
• Cross-instance Sync - Share protocols across MCP instances

Monitoring & Dashboard

• Real-time Web Dashboard - Live UI at http://localhost:3456 with Server-Sent Events
• Live Terminal Streaming - Watch worker output with ANSI color support
• Review Worker Visibility - Code and architecture review progress in dashboard
• Violation Tracking - Audit log of all protocol violations
• Git Checkpoints - Commit progress after each feature

Repository Setup

• Auto-Configuration - Set up CI/CD, issue templates, and documentation in parallel
• Platform Detection - GitHub, GitLab, Gitea, Bitbucket, Azure DevOps support
• Project Analysis - Detects languages, frameworks, and adapts configuration
• Merge Mode - Preserves existing configs by default, with optional force overwrite

Quick Start

Prerequisites

• Node.js 18+
• tmux (brew install tmux on macOS)
• Claude Code CLI

Installation

One-liner install (recommended):

curl -fsSL https://raw.githubusercontent.com/cj-vana/claude-swarm/main/install.sh | bash

This will clone the repo, build, register the MCP server, and install the /swarm skill.

Manual installation

git clone https://github.com/cj-vana/claude-swarm.git
cd claude-swarm
npm install
npm run build

# Add to Claude Code
claude mcp add claude-swarm --scope user -- node $(pwd)/dist/index.js

# Install the skill (optional but recommended)
mkdir -p ~/.claude/skills/swarm && cp skill/SKILL.md ~/.claude/skills/swarm/

Basic Usage

Tell Claude to use the swarm:

Use /swarm to build a REST API with authentication, user management, and tests

Or follow the workflow phases manually:

Phase 1: Setup
  → orchestrator_init - Initialize session with features
  → configure_verification - Set up test/build commands
  → set_dependencies - Define feature order

Phase 2: Pre-Work (per feature)
  → get_feature_complexity - Check if competitive planning needed
  → enrich_feature - Add relevant context

Phase 3: Execute
  → start_worker or start_parallel_workers

Phase 4: Monitor
  → sleep 180 - Wait before checking
  → check_worker (heartbeat: true) - Lightweight status
  → send_worker_message - Guide if stuck

Phase 5: Complete
  → run_verification - Run tests
  → mark_complete - Record success/failure
  → commit_progress - Git checkpoint

Phase 6: Review
  → check_reviews - Monitor automated reviews
  → get_review_results - See findings

Protocol System

Protocols define behavioral constraints that govern worker actions, enabling 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 report
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

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.*", "**/credentials.json"]
      },
      "severity": "error",
      "message": "Cannot access files that may contain secrets"
    }
  ],
  "enforcement": {
    "mode": "strict",
    "preExecution": true,
    "postExecution": true,
    "onViolation": "block"
  }
}

Protocol Workflow

1. protocol_register - Register a new protocol
2. protocol_activate - Activate for enforcement
3. start_worker - Workers are validated against active protocols
4. [worker runs with continuous monitoring]
5. get_violations - Review any constraint violations

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

Base Constraints (cannot be overridden): - Certain tools always denied (e.g., dangerous system commands) - Critical paths always protected (e.g., /etc, system files) - Maximum privilege ceiling enforced

Competitive Planning

For complex features, spawn two planners with different approaches:

1. get_feature_complexity(featureId)     # Analyze complexity (0-100)
2. start_competitive_planning(featureId) # Spawn Planner A & B
3. [wait for planners to complete]
4. evaluate_plans(featureId)             # Compare and pick winner
5. start_worker(featureId)               # Implement with winning plan

• Planner A: Incremental, safe approach
• Planner B: Elegant, innovative approach
• Threshold: Features scoring 60+ trigger competitive planning

Confidence Monitoring

Real-time confidence scoring detects struggling workers:

Signal	Weight	Measures
Tool Activity	35%	Read->Edit->Test cycles, stuck loops
Self-Reported	35%	Worker writes to .confidence file
Output Analysis	30%	Error patterns, frustration language

Levels: High (80-100), Medium (50-79), Low (25-49), Critical (0-24)

set_confidence_threshold(35)       # Configure alert level
get_worker_confidence(featureId)   # Get detailed breakdown

Post-Completion Reviews

Automated code and architecture reviews run after all workers complete:

1. All features complete -> session status changes to "reviewing"
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. Session completes with review summary

Review workers output structured JSON findings: - .claude/orchestrator/workers/code-review.findings.json - .claude/orchestrator/workers/architecture-review.findings.json

Severity levels: clean, minor, moderate, major, critical

Acting on Review Findings

Convert review findings into actionable features:

# View available issues from reviews
implement_review_suggestions(projectDir)

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

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

Configure or trigger manually:

configure_reviews(enabled: true, skipOnFailure: false)
run_review(reviewTypes: ["code", "architecture"])
get_review_results(format: "detailed")

Repository Setup

Automatically configure repositories with development best practices:

# Analyze repository freshness and missing configs
setup_analyze(projectDir)

# Initialize setup with parallel workers
setup_init(projectDir)

# Check setup progress
setup_status(projectDir)

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
Dependabot	Automated dependency updates	.github/dependabot.yml
Release Please	Automated version bumps and changelogs	.github/workflows/release-please.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

# Skip specific config types
setup_init(projectDir, skipConfigs: ["dependabot", "release-please"])

# Force overwrite existing files
setup_init(projectDir, force: true)

# Override platform detection
setup_init(projectDir, platform: "gitlab")

Feature Rollback

The orchestrator creates git snapshot branches before each worker starts, enabling safe rollback of failed features.

How Rollback Works

1. Snapshot Creation: start_worker creates swarm/{featureId} branch at current HEAD
2. Worker Execution: Worker makes changes to working directory
3. On Failure: Use rollback_feature to restore pre-worker state

Rollback Tools

Tool	Description
rollback_feature	Restore files changed by a worker
check_rollback_conflicts	Check for conflicts with other workers

Usage

# Rollback all files changed by feature
rollback_feature(projectDir, featureId: "feature-1")

# Rollback specific files only
rollback_feature(projectDir, featureId: "feature-1", files: ["src/component.ts"])

Warning: When rolling back in parallel worker environments, other workers' changes to the same files will also be reverted.

Web Dashboard

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

• Session Overview - Progress bar, feature counts, session statistics
• Feature Cards - Status, dependencies, worker assignment
• Live Terminal Output - Real-time streaming with ANSI color support
• Review Worker Progress - Code and architecture review visibility
• Dark Mode - Automatic theme detection

Dashboard API

The dashboard exposes a REST API for programmatic access:

Endpoint	Method	Description
/api/status	GET	Session overview with elapsed time and progress summary
/api/features	GET	Feature list with details (supports ?status= filter)
/api/workers	GET	All worker statuses with summary counts
/api/workers/:featureId/output	GET (SSE)	Stream worker terminal output in real-time
/api/review-workers	GET	Review worker statuses and findings summary
/api/review-workers/:type/output	GET (SSE)	Stream review worker output
/api/logs	GET	Progress log entries (supports ?limit=N)
/api/stats	GET	Session statistics (completion times, success rates)
/api/events	GET (SSE)	Real-time updates for all session changes
/health	GET	Health check endpoint

Server-Sent Events (/api/events): - status - Session status changes - feature - Feature status updates - worker - Active worker count changes - reviewWorker - Review worker status updates - log - New progress log entries - heartbeat - Keep-alive (every 15s)

Architecture

``` +-----------------------------------------------------------------------+ | MCP Server | | (Persistent state, survives compaction) | | | | +--------------+ +--------------+ +--------------+ | | | State | | Worker | | Protocol | | | | Manager | | Manager | | Registry | | | +--------------+ +--------------+ +--------------+ | | | | | | | +------+-----------------+------------------+------------------------+| | | Enforcement Engine | Resolver | Context Enricher || | +--------------------------------------------------------------------+| | | | | +---------------------------+----------------------------------------+| | | Review Manager | Complexity Detector | Plan Evaluator || | +--------------------------------------------------------------------+| | | | | +---------------------------+----------------------------------------+| | | Web Dashboard (SSE) || | +--------------------------------------------------------------------+| +--------------------------------+--------------------------------------+ | MCP Protocol +--------------------------------+--------------------------------------+ | Claude Code | |