claude-swarm

<p align="center"> <img src="assets/banner.png" alt="Claude Swarm - Parallel AI Workers" width="100%"> </p> <p align="center"> <strong>An MCP server for orchestrating parallel Claude Code worker swarms with protocol-based behavioral governance.</strong><br> Enables multi-hour autonomous coding sessions with persistent state, parallel workers, and runtime enforcement of behavioral constraints. </p> <p align="center"> <a href="#installation">Installation</a> • <a href="#quick-start">Quick Start</a> • <a href="#web-dashboard">Dashboard</a> • <a href="#protocol-system">Protocols</a> • <a href="#mcp-tools-reference">Tools</a> </p> --- ## Features ### Worker Orchestration - **Persistent State** - Session state survives context compaction via MCP server - **Parallel Workers** - Run multiple Claude Code workers simultaneously via tmux - **Git Worktree Isolation** - Workers run in isolated git worktrees for safe parallel modification - **Worker Plan Mode** - Workers analyze codebases and produce plans before implementing (auto-approved) - **Competitive Planning** - Complex features get two competing implementation plans - **Confidence Monitoring** - Multi-signal scoring detects struggling workers - **Enforced Verification** - Test-as-supervisor pattern with configurable verification commands - **Auto-retry** - Failed features automatically retry with configurable limits - **Feature Dependencies** - Define execution order between features - **File-Based Task Locking** - Atomic mutual exclusion prevents workers from conflicting - **Post-Completion Reviews** - Automated code and architecture reviews with actionable findings ### Long-Running Autonomy - **Ralph Loop** - Fresh Claude context per iteration eliminates context rot for long sessions - **Days-Long Sessions** - Supports hours/days of autonomous execution with checkpointing - **Crash Recovery** - Automatic session resumption after crashes or machine restarts - **Failure Pattern Learning** - Records what works/fails for future worker prompts ### 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 ## How It Works The orchestrator pattern separates concerns for reliable long-running sessions: - **Orchestrator (Claude Code)**: Plans work, monitors progress, makes decisions - **MCP Server**: Maintains persistent state that survives context compaction - **Workers**: Isolated Claude Code sessions in git worktrees via tmux that implement individual features - **Protocols**: Behavioral constraints governing what workers can/cannot do - **Ralph Loop**: External bash loop that launches fresh Claude sessions per iteration, with state persisted to the filesystem (progress files, git history) ### Worker Lifecycle Workers follow a two-phase lifecycle when plan mode is enabled (complexity >= 30): 1. **Plan Phase** - Worker runs with read-only tools (Read, Glob, Grep, Write), analyzes the codebase, and produces a structured plan 2. **Auto-Review** - Orchestrator scores the plan on test strategy, risk assessment, file specificity, and step count 3. **Implement Phase** - Worker runs with full tools, following the approved plan step by step ### Ralph Loop (Long-Running Autonomy) For long-running features, the Ralph Loop replaces single long-lived sessions: 1. Each iteration launches a **fresh Claude session** (no context rot) 2. State persists via **filesystem**: progress.md, git history, .done files 3. Prompt **re-reads current state** each iteration (self-reloading context) 4. Configurable stopping conditions: completion marker, time limit, max iterations 5. Git diff injected into prompt so worker sees what changed ### Session Resilience Sessions survive crashes and machine restarts: - **Checkpointing** - State snapshots every ~15 minutes while workers are running - **Heartbeat Detection** - PID-based liveness detection identifies stale sessions - **Crash Recovery** - `resume_session` detects crashes, loads checkpoints, restarts dead workers - **Graceful Shutdown** - `shutdown_session` creates checkpoint and stops workers cleanly This separation enables: - **Parallel execution**: Multiple workers implement features simultaneously - **State persistence**: Session state survives context compaction via the MCP server - **Failure recovery**: Workers can retry, rollback, or be guided when stuck - **Behavioral governance**: Protocols enforce constraints on worker actions ## Quick Start ### Prerequisites - Node.js 18+ - tmux (`brew install tmux` on macOS) - Claude Code CLI ### Installation **One-liner install** (recommended): ```bash 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. <details> <summary><strong>Manual installation</strong></summary> ```bash 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/ ``` </details> ### 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 ``` ### The `/swarm` Skill The `/swarm` skill provides guided orchestration with a complete workflow: ``` Use /swarm to build a REST API with authentication, user management, and tests ``` The skill automates: - **Phase 0**: Repository readiness check (runs `setup_analyze`) - **Phase 1**: Session setup with feature decomposition - **Phase 2**: Pre-work preparation (complexity analysis, context enrichment) - **Phase 3**: Execution (manual or auto-orchestration) - **Phase 4**: Monitoring loop with confidence tracking - **Phase 5**: Completion verification and git checkpoints - **Phase 6**: Post-completion reviews **Installing the skill:** ```bash mkdir -p ~/.claude/skills/swarm && cp skill/SKILL.md ~/.claude/skills/swarm/ ``` See `skill/SKILL.md` for the complete workflow reference. ## 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 ```json { "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 ``` ## Auto-Orchestration For fully autonomous execution, use `auto_orchestrate`: ``` auto_orchestrate(projectDir, strategy: "adaptive", maxConcurrent: 5) ``` This handles Phases 3-5 automatically: - Schedules workers based on dependencies - Monitors progress and handles failures - Runs verification commands - Marks features complete - Commits progress at checkpoints ### Scheduling Strategies | Strategy | Behavior | |----------|----------| | `breadth-first` | Maximize parallel execution of independent features | | `depth-first` | Focus on unblocking dependent feature chains | | `adaptive` | System decides based on dependency graph (default) | ### When to Use - **Auto-orchestration**: Large feature sets, hands-off execution - **Manual orchestration**: Fine-grained control, complex dependencies, debugging ## 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 ```bash # 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  *Claude Code orchestrates workers through the MCP Server. Workers run in isolated tmux sessions and share access to the project codebase. The dashboard provides real-time monitoring via SSE.* ## MCP Tools Reference ### Core Orchestration (3 tools) | Tool | Description | |------|-------------| | `orchestrator_init` | Start session with task and features | | `orchestrator_status` | Get current state (use after compaction) | | `orchestrator_reset` | Clear state and kill all workers | ### Worker Management (9 tools) | Tool | Description | |------|-------------| | `start_worker` | Launch worker for a feature | | `start_parallel_workers` | Launch multiple workers simultaneously | | `start_ralph_loop` | Launch worker with Ralph Loop (fresh context per iteration) | | `validate_workers` | Pre-flight validation before parallel execution | | `check_worker` | Get worker output (supports heartbeat mode) | | `check_all_workers` | Check all active workers at once | | `send_worker_message` | Send instructions to running worker | | `configure_plan_mode` | Enable/configure worker plan-before-implement mode | | `configure_ralph_loop` | Enable/configure Ralph Loop execution defaults | ### Competitive Planning (3 tools) | Tool | Description | |------|-------------| | `get_feature_complexity` | Analyze complexity score | | `start_competitive_planning` | Spawn 2 planners with different approaches | | `evaluate_plans` | Compare plans and select winner | ### Confidence Monitoring (2 tools) | Tool | Description | |------|-------------| | `get_worker_confidence` | Get detailed confidence breakdown | | `set_confidence_threshold` | Configure alert threshold | ### Feature Management (6 tools) | Tool | Description | |------|-------------| | `mark_complete` | Mark feature done/failed (auto-retry) | | `retry_feature` | Reset failed feature for retry | | `run_verification` | Run tests/build commands | | `add_feature` | Add discovered work | | `set_dependencies` | Define feature dependencies | | `configure_verification` | Set pre-completion verification commands | ### Pre-Completion Verification Configure commands that workers must run before marking features complete: ``` configure_verification(projectDir, commands: ["npm test", "npx tsc --noEmit"]) ``` Workers will run these commands and fix any errors before completion. Allowed commands include: - `npm test`, `npm run test`, `yarn test`, `pnpm test` - `npx tsc --noEmit`, `npx vitest`, `npx jest` - `pytest`, `python -m pytest` - `cargo test`, `cargo check` - `go test`, `make test` ### Session & Progress (7 tools) | Tool | Description | |------|-------------| | `get_progress_log` | View history (paginated) | | `get_session_stats` | Success rates and timing | | `pause_session` | Pause and stop all workers | | `resume_session` | Resume paused session (supports crash recovery) | | `shutdown_session` | Graceful shutdown with checkpoint | | `commit_progress` | Create git checkpoint | | `auto_orchestrate` | Hands-free orchestration until completion | ### Feature Rollback (2 tools) | Tool | Description | |------|-------------| | `rollback_feature` | Restore files changed by a worker | | `check_rollback_conflicts` | Check for conflicts with other workers | ### Post-Completion Reviews (5 tools) | Tool | Description | |------|-------------| | `run_review` | Manually trigger code/architecture reviews | | `check_reviews` | Monitor review worker status | | `get_review_results` | Get aggregated findings (summary/detailed/json) | | `configure_reviews` | Set auto-review preferences | | `implement_review_suggestions` | Convert review findings into features | ### Repository Setup (3 tools) | Tool | Description | |------|-------------| | `setup_analyze` | Analyze repo freshness and missing configs | | `setup_init` | Initialize repo configuration with parallel workers | | `setup_status` | Check setup progress | ### Protocol Management (5 tools) | Tool | Description | |------|-------------| | `protocol_register` | Register a new protocol | | `protocol_activate` | Activate protocol for enforcement | | `protocol_deactivate` | Deactivate protocol | | `protocol_list` | List all registered protocols | | `protocol_status` | Get protocol details and violations | ### Protocol Enforcement (4 tools) | Tool | Description | |------|-------------| | `validate_feature_protocols` | Check if feature can run under active protocols | | `get_violations` | Get recorded violations (paginated) | | `resolve_violation` | Mark violation as resolved | | `get_audit_log` | Get protocol audit history | ### LLM Protocol Generation (5 tools) | Tool | Description | |------|-------------| | `get_base_constraints` | View immutable base constraints | | `propose_protocol` | Submit a protocol proposal | | `review_proposals` | List pending proposals with risk scores | | `approve_protocol` | Approve a protocol proposal | | `reject_protocol` | Reject a protocol proposal | ### Protocol Networking (4 tools) | Tool | Description | |------|-------------| | `export_protocols` | Export protocols to shareable bundle | | `import_protocols` | Import protocols from bundle | | `sync_protocols` | Sync with peer instances | | `discover_protocols` | Discover peer MCP instances | ### Context Management (4 tools) | Tool | Description | |------|-------------| | `enrich_feature` | Auto-enrich feature with relevant docs and code | | `set_feature_context` | Manually set feature context | | `get_feature_graph` | View feature dependency graph with context | | `route_feature` | Configure worker routing preferences | ## Files Created ``` your-project/ ├── .claude/orchestrator/ │ ├── state.json # Session state │ ├── feature_list.json # Feature status │ ├── protocols/ │ │ ├── registry.json # Protocol definitions │ │ ├── active.json # Active protocols │ │ ├── violations.json # Violation records │ │ ├── audit.json # Audit log │ │ └── proposals/ # Pending proposals │ ├── sync/ # Cross-instance sync │ ├── checkpoints/ # Session checkpoints for crash recovery │ │ └── *.json # Timestamped state snapshots │ ├── heartbeat.json # Orchestrator liveness detection │ ├── learnings.json # Failure pattern learning │ ├── locks/ # File-based mutual exclusion │ │ └── *.lock # Per-file lock files │ ├── worktrees/ # Git worktree directories │ └── workers/ │ ├── *.prompt # Worker prompts │ ├── *.log # Worker output logs │ ├── *.done # Completion markers │ ├── *.status # Worker status │ ├── *.plan.json # Competitive plans │ ├── *.confidence # Self-reported confidence │ ├── *.worker-plan.json # Worker plan-phase output │ ├── *.plan-done # Plan phase completion markers │ ├── *.progress.md # Ralph Loop progress files │ ├── code-review.findings.json # Code review results │ └── architecture-review.findings.json # Architecture review results ├── claude-progress.txt # Human-readable log └── init.sh # Environment setup ``` ## Configuration | Variable | Default | Description | |----------|---------|-------------| | `DASHBOARD_PORT` | `3456` | Dashboard HTTP port | | `ENABLE_DASHBOARD` | `true` | Set to `false` to disable | ## Security ### Input Validation - **Path traversal protection** - All file paths validated against project directory - **Cryptographically secure IDs** - Uses `crypto.randomUUID()` - **Symlink escape prevention** - Real paths validated before file operations - **Input validation** - All inputs validated with Zod schemas ### Regex Safety (ReDoS Protection) - **Pattern validation** - `isDangerousRegexPattern()` detects catastrophic backtracking - **Safe regex testing** - `safeRegexTest()` falls back to literal matching for dangerous patterns - **Glob-to-regex conversion** - Proper metacharacter escaping prevents injection ### Memory Safety - **Bounded collections** - Operation counts, alerts, and observed patterns have maximum limits - **LRU eviction** - Least-recently-used entries removed when limits reached (max 50 cached managers) - **Timestamp truncation** - Historical data pruned to prevent unbounded growth ### Network Safety - **Localhost-only CORS** - Dashboard only accepts requests from localhost origins - **No external network access** - Workers operate in isolated tmux sessions ### Execution Safety - **Fail-closed enforcement** - Unknown constraint types block by default - **Command allowlist** - Only safe verification commands allowed - **No shell injection** - Uses `execFile` with arguments, prompts via files - **Circuit breaker pattern** - Monitor auto-stops after repeated failures - **Review worker isolation** - Read-only tools (no Bash access) ### Protocol Security - **Base constraints** - Immutable security rules cannot be overridden - **Proposal validation** - LLM-generated protocols checked against security boundaries - **Token-based matching** - Tool prohibition uses exact token matching, not substring ## Inspiration - [Anthropic's "Effective harnesses for long-running agents"](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) - [Ralph Loop: A Continuous Iteration Paradigm for AI Agents](https://www.alibabacloud.com/blog/from-react-to-ralph-loop-a-continuous-iteration-paradigm-for-ai-agents_602799) - [Claude Code Agent Teams](https://code.claude.com/docs/en/agent-teams) - [MAKER: "Solving a Million-Step LLM Task with Zero Errors"](https://arxiv.org/abs/2511.09030) - [Multi-Agent Collaboration via Evolving Orchestration](https://arxiv.org/abs/2505.19591) - [AFlow: Automatic Workflow Optimization](https://arxiv.org/abs/2410.10762) - [AgentsNet: Coordinating Multi-Agent Networks](https://arxiv.org/html/2507.08616v1) ## Troubleshooting ### "No active session" Run `orchestrator_status` to check state, or `orchestrator_init` to start fresh. ### Worker seems stuck 1. `check_worker(featureId)` to see current output 2. `get_worker_confidence(featureId)` to check confidence score 3. `send_worker_message(featureId, "guidance")` to provide direction 4. If truly stuck, `mark_complete(featureId, success: false)` triggers auto-retry ### Lost context after compaction Call `orchestrator_status(projectDir)` - the MCP server maintains all state externally. ### Feature has unmet dependencies 1. Check dependencies with `orchestrator_status` 2. Complete dependency features first 3. Or use `set_dependencies` to modify the chain ### Protocol violations blocking work 1. `get_violations()` to see what was violated 2. `resolve_violation(violationId, resolution)` if false positive 3. Adjust protocol constraints if too restrictive ### Debugging tmux sessions ```bash # List all worker sessions tmux list-sessions | grep cc-worker # Attach to a worker session tmux attach -t cc-worker-feature-1-abc123 # Capture recent output tmux capture-pane -t <session-name> -p -S -100 ``` ### Session crashed, how to recover Use `resume_session(projectDir)` - it automatically detects crashes via stale heartbeat, loads the latest checkpoint, and restarts dead workers. Set `restartDeadWorkers: true` (default) to auto-restart Ralph Loop workers that were running. ### Worker keeps failing verification Check the Ralph Loop progress file (`.claude/orchestrator/workers/{featureId}.progress.md`) for error patterns across iterations. The progress file records issues encountered in each iteration, helping identify systematic problems. ### Plan mode is too slow Lower the complexity threshold (default: 30) via `configure_plan_mode(projectDir, { complexityThreshold: 50 })` so only higher-complexity features trigger planning. Or disable per-feature by setting `planMode: false` on the feature. ### Monitor stops unexpectedly The monitor auto-stops after 5 consecutive errors (circuit breaker). Check MCP server logs and restart if needed. ## Limitations - Requires tmux (WSL on Windows) - Workers use your Claude Code subscription - Protocol enforcement is observational (monitors but doesn't intercept tool calls) - Complex feature detection is heuristic-based ## Contributing Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. ## License MIT