Skip to content
Back to search

claude-swarm

SkillWorks with Claude CodeGitHub

MCP server for orchestrating parallel Claude Code worker swarms with protocol-based behavioral governance, persistent state, and real-time monitoring dashboard

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cj-vana--claude-swarm/badge.svg)](/listings/cj-vana--claude-swarm)

HTML

<a href="/listings/cj-vana--claude-swarm"><img src="/api/listings/cj-vana--claude-swarm/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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.

<details> <summary><strong>Manual installation</strong></summary>

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:**

mkdir -p ~/.claude/skills/swarm && cp skill/SKILL.md ~/.claude/skills/swarm/

See `skill/SKILL.md` for the complete workflow reference.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 773 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="assets/banner.png" alt="Claude Swarm - Parallel AI Workers" width="100%">
  3. </p>
  4. <p align="center">
  5. <strong>An MCP server for orchestrating parallel Claude Code worker swarms with protocol-based behavioral governance.</strong><br>
  6. Enables multi-hour autonomous coding sessions with persistent state, parallel workers, and runtime enforcement of behavioral constraints.
  7. </p>
  8. <p align="center">
  9. <a href="#installation">Installation</a> •
  10. <a href="#quick-start">Quick Start</a> •
  11. <a href="#web-dashboard">Dashboard</a> •
  12. <a href="#protocol-system">Protocols</a> •
  13. <a href="#mcp-tools-reference">Tools</a>
  14. </p>
  15. ---
  16. ## Features
  17. ### Worker Orchestration
  18. - **Persistent State** - Session state survives context compaction via MCP server
  19. - **Parallel Workers** - Run multiple Claude Code workers simultaneously via tmux
  20. - **Git Worktree Isolation** - Workers run in isolated git worktrees for safe parallel modification
  21. - **Worker Plan Mode** - Workers analyze codebases and produce plans before implementing (auto-approved)
  22. - **Competitive Planning** - Complex features get two competing implementation plans
  23. - **Confidence Monitoring** - Multi-signal scoring detects struggling workers
  24. - **Enforced Verification** - Test-as-supervisor pattern with configurable verification commands
  25. - **Auto-retry** - Failed features automatically retry with configurable limits
  26. - **Feature Dependencies** - Define execution order between features
  27. - **File-Based Task Locking** - Atomic mutual exclusion prevents workers from conflicting
  28. - **Post-Completion Reviews** - Automated code and architecture reviews with actionable findings
  29. ### Long-Running Autonomy
  30. - **Ralph Loop** - Fresh Claude context per iteration eliminates context rot for long sessions
  31. - **Days-Long Sessions** - Supports hours/days of autonomous execution with checkpointing
  32. - **Crash Recovery** - Automatic session resumption after crashes or machine restarts
  33. - **Failure Pattern Learning** - Records what works/fails for future worker prompts
  34. ### Protocol-Based Governance
  35. - **Behavioral Protocols** - Define constraints on what workers can/cannot do
  36. - **Pre-spawn Validation** - Verify protocols allow task before worker starts
  37. - **Continuous Monitoring** - Track constraint violations during execution
  38. - **LLM-Generated Protocols** - Workers can propose new protocols (validated against base constraints)
  39. - **Cross-instance Sync** - Share protocols across MCP instances
  40. ### Monitoring & Dashboard
  41. - **Real-time Web Dashboard** - Live UI at `http://localhost:3456` with Server-Sent Events
  42. - **Live Terminal Streaming** - Watch worker output with ANSI color support
  43. - **Review Worker Visibility** - Code and architecture review progress in dashboard
  44. - **Violation Tracking** - Audit log of all protocol violations
  45. - **Git Checkpoints** - Commit progress after each feature
  46. ### Repository Setup
  47. - **Auto-Configuration** - Set up CI/CD, issue templates, and documentation in parallel
  48. - **Platform Detection** - GitHub, GitLab, Gitea, Bitbucket, Azure DevOps support
  49. - **Project Analysis** - Detects languages, frameworks, and adapts configuration
  50. - **Merge Mode** - Preserves existing configs by default, with optional force overwrite
  51. ## How It Works
  52. The orchestrator pattern separates concerns for reliable long-running sessions:
  53. - **Orchestrator (Claude Code)**: Plans work, monitors progress, makes decisions
  54. - **MCP Server**: Maintains persistent state that survives context compaction
  55. - **Workers**: Isolated Claude Code sessions in git worktrees via tmux that implement individual features
  56. - **Protocols**: Behavioral constraints governing what workers can/cannot do
  57. - **Ralph Loop**: External bash loop that launches fresh Claude sessions per iteration, with state persisted to the filesystem (progress files, git history)
  58. ### Worker Lifecycle
  59. Workers follow a two-phase lifecycle when plan mode is enabled (complexity >= 30):
  60. 1. **Plan Phase** - Worker runs with read-only tools (Read, Glob, Grep, Write), analyzes the codebase, and produces a structured plan
  61. 2. **Auto-Review** - Orchestrator scores the plan on test strategy, risk assessment, file specificity, and step count
  62. 3. **Implement Phase** - Worker runs with full tools, following the approved plan step by step
  63. ### Ralph Loop (Long-Running Autonomy)
  64. For long-running features, the Ralph Loop replaces single long-lived sessions:
  65. 1. Each iteration launches a **fresh Claude session** (no context rot)
  66. 2. State persists via **filesystem**: progress.md, git history, .done files
  67. 3. Prompt **re-reads current state** each iteration (self-reloading context)
  68. 4. Configurable stopping conditions: completion marker, time limit, max iterations
  69. 5. Git diff injected into prompt so worker sees what changed
  70. ### Session Resilience
  71. Sessions survive crashes and machine restarts:
  72. - **Checkpointing** - State snapshots every ~15 minutes while workers are running
  73. - **Heartbeat Detection** - PID-based liveness detection identifies stale sessions
  74. - **Crash Recovery** - `resume_session` detects crashes, loads checkpoints, restarts dead workers
  75. - **Graceful Shutdown** - `shutdown_session` creates checkpoint and stops workers cleanly
  76. This separation enables:
  77. - **Parallel execution**: Multiple workers implement features simultaneously
  78. - **State persistence**: Session state survives context compaction via the MCP server
  79. - **Failure recovery**: Workers can retry, rollback, or be guided when stuck
  80. - **Behavioral governance**: Protocols enforce constraints on worker actions
  81. ## Quick Start
  82. ### Prerequisites
  83. - Node.js 18+
  84. - tmux (`brew install tmux` on macOS)
  85. - Claude Code CLI
  86. ### Installation
  87. **One-liner install** (recommended):
  88. ```bash
  89. curl -fsSL https://raw.githubusercontent.com/cj-vana/claude-swarm/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 117 on GitHub
  90. ```
  91. This will clone the repo, build, register the MCP server, and install the `/swarm` skill.
  92. <details>
  93. <summary><strong>Manual installation</strong></summary>
  94. ```bash
  95. git clone https://github.com/cj-vana/claude-swarm.git
  96. cd claude-swarm
  97. npm install
  98. npm run build
  99. # Add to Claude Code
  100. claude mcp add claude-swarm --scope user -- node $(pwd)/dist/index.js
  101. # Install the skill (optional but recommended)
  102. mkdir -p ~/.claude/skills/swarm && cp skill/SKILL.md ~/.claude/skills/swarm/
  103. ```
  104. </details>
  105. ### Basic Usage
  106. Tell Claude to use the swarm:
  107. ```
  108. Use /swarm to build a REST API with authentication, user management, and tests
  109. ```
  110. Or follow the workflow phases manually:
  111. ```
  112. Phase 1: Setup
  113. → orchestrator_init - Initialize session with features
  114. → configure_verification - Set up test/build commands
  115. → set_dependencies - Define feature order
  116. Phase 2: Pre-Work (per feature)
  117. → get_feature_complexity - Check if competitive planning needed
  118. → enrich_feature - Add relevant context
  119. Phase 3: Execute
  120. → start_worker or start_parallel_workers
  121. Phase 4: Monitor
  122. → sleep 180 - Wait before checking
  123. → check_worker (heartbeat: true) - Lightweight status
  124. → send_worker_message - Guide if stuck
  125. Phase 5: Complete
  126. → run_verification - Run tests
  127. → mark_complete - Record success/failure
  128. → commit_progress - Git checkpoint
  129. Phase 6: Review
  130. → check_reviews - Monitor automated reviews
  131. → get_review_results - See findings
  132. ```
  133. ### The `/swarm` Skill
  134. The `/swarm` skill provides guided orchestration with a complete workflow:
  135. ```
  136. Use /swarm to build a REST API with authentication, user management, and tests
  137. ```
  138. The skill automates:
  139. - **Phase 0**: Repository readiness check (runs `setup_analyze`)
  140. - **Phase 1**: Session setup with feature decomposition
  141. - **Phase 2**: Pre-work preparation (complexity analysis, context enrichment)
  142. - **Phase 3**: Execution (manual or auto-orchestration)
  143. - **Phase 4**: Monitoring loop with confidence tracking
  144. - **Phase 5**: Completion verification and git checkpoints
  145. - **Phase 6**: Post-completion reviews
  146. **Installing the skill:**
  147. ```bash
  148. mkdir -p ~/.claude/skills/swarm && cp skill/SKILL.md ~/.claude/skills/swarm/
  149. ```
  150. See `skill/SKILL.md` for the complete workflow reference.
  151. ## Protocol System
  152. Protocols define behavioral constraints that govern worker actions, enabling safe autonomous operation with clear boundaries.
  153. ### Constraint Types
  154. | Type | Description | Example |
  155. |------|-------------|---------|
  156. | `tool_restriction` | Allow/deny specific tools | Only allow Read, Glob, Grep |
  157. | `file_access` | Control file system access | Block access to `.env` files |
  158. | `output_format` | Require specific output patterns | Must include test coverage report |
  159. | `behavioral` | High-level behavior rules | Require confirmation before destructive actions |
  160. | `temporal` | Time-based constraints | Max 30 minutes per feature |
  161. | `resource` | Resource usage limits | Max 100 file operations |
  162. | `side_effect` | Control external effects | No network requests, no git push |
  163. ### Example Protocol
  164. ```json
  165. {
  166. "id": "safe-refactoring-v1",
  167. "name": "Safe Refactoring Protocol",
  168. "version": "1.0.0",
  169. "priority": 100,
  170. "constraints": [
  171. {
  172. "id": "no-secrets",
  173. "type": "file_access",
  174. "rule": {
  175. "type": "file_access",
  176. "deniedPaths": ["**/.env", "**/secrets.*", "**/credentials.json"]
  177. },
  178. "severity": "error",
  179. "message": "Cannot access files that may contain secrets"
  180. }
  181. ],
  182. "enforcement": {
  183. "mode": "strict",
  184. "preExecution": true,
  185. "postExecution": true,
  186. "onViolation": "block"
  187. }
  188. }
  189. ```
  190. ### Protocol Workflow
  191. ```
  192. 1. protocol_register - Register a new protocol
  193. 2. protocol_activate - Activate for enforcement
  194. 3. start_worker - Workers are validated against active protocols
  195. 4. [worker runs with continuous monitoring]
  196. 5. get_violations - Review any constraint violations
  197. ```
  198. ### LLM-Generated Protocols
  199. Workers can propose new protocols validated against immutable base constraints:
  200. ```
  201. 1. get_base_constraints - View immutable security rules
  202. 2. propose_protocol - Worker submits proposal
  203. 3. review_proposals - See pending proposals with risk scores
  204. 4. approve_protocol / reject_protocol - Human review for high-risk
  205. ```
  206. **Base Constraints** (cannot be overridden):
  207. - Certain tools always denied (e.g., dangerous system commands)
  208. - Critical paths always protected (e.g., `/etc`, system files)
  209. - Maximum privilege ceiling enforced
  210. ## Competitive Planning
  211. For complex features, spawn two planners with different approaches:
  212. ```
  213. 1. get_feature_complexity(featureId) # Analyze complexity (0-100)
  214. 2. start_competitive_planning(featureId) # Spawn Planner A & B
  215. 3. [wait for planners to complete]
  216. 4. evaluate_plans(featureId) # Compare and pick winner
  217. 5. start_worker(featureId) # Implement with winning plan
  218. ```
  219. - **Planner A**: Incremental, safe approach
  220. - **Planner B**: Elegant, innovative approach
  221. - **Threshold**: Features scoring 60+ trigger competitive planning
  222. ## Confidence Monitoring
  223. Real-time confidence scoring detects struggling workers:
  224. | Signal | Weight | Measures |
  225. |--------|--------|----------|
  226. | Tool Activity | 35% | Read->Edit->Test cycles, stuck loops |
  227. | Self-Reported | 35% | Worker writes to `.confidence` file |
  228. | Output Analysis | 30% | Error patterns, frustration language |
  229. **Levels**: High (80-100), Medium (50-79), Low (25-49), Critical (0-24)
  230. ```
  231. set_confidence_threshold(35) # Configure alert level
  232. get_worker_confidence(featureId) # Get detailed breakdown
  233. ```
  234. ## Auto-Orchestration
  235. For fully autonomous execution, use `auto_orchestrate`:
  236. ```
  237. auto_orchestrate(projectDir, strategy: "adaptive", maxConcurrent: 5)
  238. ```
  239. This handles Phases 3-5 automatically:
  240. - Schedules workers based on dependencies
  241. - Monitors progress and handles failures
  242. - Runs verification commands
  243. - Marks features complete
  244. - Commits progress at checkpoints
  245. ### Scheduling Strategies
  246. | Strategy | Behavior |
  247. |----------|----------|
  248. | `breadth-first` | Maximize parallel execution of independent features |
  249. | `depth-first` | Focus on unblocking dependent feature chains |
  250. | `adaptive` | System decides based on dependency graph (default) |
  251. ### When to Use
  252. - **Auto-orchestration**: Large feature sets, hands-off execution
  253. - **Manual orchestration**: Fine-grained control, complex dependencies, debugging
  254. ## Post-Completion Reviews
  255. Automated code and architecture reviews run after all workers complete:
  256. ```
  257. 1. All features complete -> session status changes to "reviewing"
  258. 2. Code review worker analyzes: bugs, security, style, test coverage
  259. 3. Architecture review worker analyzes: coupling, patterns, scalability
  260. 4. Findings aggregated into progress log
  261. 5. Session completes with review summary
  262. ```
  263. Review workers output structured JSON findings:
  264. - `.claude/orchestrator/workers/code-review.findings.json`
  265. - `.claude/orchestrator/workers/architecture-review.findings.json`
  266. **Severity levels**: clean, minor, moderate, major, critical
  267. ### Acting on Review Findings
  268. Convert review findings into actionable features:
  269. ```
  270. # View available issues from reviews
  271. implement_review_suggestions(projectDir)
  272. # Create features from specific issues
  273. implement_review_suggestions(projectDir, issueIndices: [0, 2, 5])
  274. # Auto-select warnings and errors
  275. implement_review_suggestions(projectDir, autoSelect: true, minSeverity: "warning")
  276. ```
  277. Configure or trigger manually:
  278. ```
  279. configure_reviews(enabled: true, skipOnFailure: false)
  280. run_review(reviewTypes: ["code", "architecture"])
  281. get_review_results(format: "detailed")
  282. ```
  283. ## Repository Setup
  284. Automatically configure repositories with development best practices:
  285. ```
  286. # Analyze repository freshness and missing configs
  287. setup_analyze(projectDir)
  288. # Initialize setup with parallel workers
  289. setup_init(projectDir)
  290. # Check setup progress
  291. setup_status(projectDir)
  292. ```
  293. ### Configuration Types
  294. | Type | Description | Files Created |
  295. |------|-------------|---------------|
  296. | **CLAUDE.md** | Project guidance for Claude Code | `CLAUDE.md` |
  297. | **GitHub CI** | Build, test, lint workflows | `.github/workflows/ci.yml` |
  298. | **Dependabot** | Automated dependency updates | `.github/dependabot.yml` |
  299. | **Release Please** | Automated version bumps and changelogs | `.github/workflows/release-please.yml` |
  300. | **Issue Templates** | Structured bug/feature reporting | `.github/ISSUE_TEMPLATE/*.yml` |
  301. | **PR Template** | Consistent pull request descriptions | `.github/PULL_REQUEST_TEMPLATE.md` |
  302. | **CONTRIBUTING.md** | Contribution guidelines | `CONTRIBUTING.md` |
  303. | **SECURITY.md** | Security policy and vulnerability reporting | `SECURITY.md` |
  304. ### Customization
  305. ```bash
  306. # Skip specific config types
  307. setup_init(projectDir, skipConfigs: ["dependabot", "release-please"])
  308. # Force overwrite existing files
  309. setup_init(projectDir, force: true)
  310. # Override platform detection
  311. setup_init(projectDir, platform: "gitlab")
  312. ```
  313. ## Feature Rollback
  314. The orchestrator creates git snapshot branches before each worker starts, enabling safe rollback of failed features.
  315. ### How Rollback Works
  316. 1. **Snapshot Creation**: `start_worker` creates `swarm/{featureId}` branch at current HEAD
  317. 2. **Worker Execution**: Worker makes changes to working directory
  318. 3. **On Failure**: Use `rollback_feature` to restore pre-worker state
  319. ### Rollback Tools
  320. | Tool | Description |
  321. |------|-------------|
  322. | `rollback_feature` | Restore files changed by a worker |
  323. | `check_rollback_conflicts` | Check for conflicts with other workers |
  324. ### Usage
  325. ```
  326. # Rollback all files changed by feature
  327. rollback_feature(projectDir, featureId: "feature-1")
  328. # Rollback specific files only
  329. rollback_feature(projectDir, featureId: "feature-1", files: ["src/component.ts"])
  330. ```
  331. **Warning**: When rolling back in parallel worker environments, other workers' changes to the same files will also be reverted.
  332. ## Web Dashboard
  333. ![Claude Swarm Dashboard](assets/dashboard.png)
  334. ![Active Workers Panel](assets/dashboard-workers.png)
  335. A real-time web dashboard is available at `http://localhost:3456`:
  336. - **Session Overview** - Progress bar, feature counts, session statistics
  337. - **Feature Cards** - Status, dependencies, worker assignment
  338. - **Live Terminal Output** - Real-time streaming with ANSI color support
  339. - **Review Worker Progress** - Code and architecture review visibility
  340. - **Dark Mode** - Automatic theme detection
  341. ### Dashboard API
  342. The dashboard exposes a REST API for programmatic access:
  343. | Endpoint | Method | Description |
  344. |----------|--------|-------------|
  345. | `/api/status` | GET | Session overview with elapsed time and progress summary |
  346. | `/api/features` | GET | Feature list with details (supports `?status=` filter) |
  347. | `/api/workers` | GET | All worker statuses with summary counts |
  348. | `/api/workers/:featureId/output` | GET (SSE) | Stream worker terminal output in real-time |
  349. | `/api/review-workers` | GET | Review worker statuses and findings summary |
  350. | `/api/review-workers/:type/output` | GET (SSE) | Stream review worker output |
  351. | `/api/logs` | GET | Progress log entries (supports `?limit=N`) |
  352. | `/api/stats` | GET | Session statistics (completion times, success rates) |
  353. | `/api/events` | GET (SSE) | Real-time updates for all session changes |
  354. | `/health` | GET | Health check endpoint |
  355. **Server-Sent Events** (`/api/events`):
  356. - `status` - Session status changes
  357. - `feature` - Feature status updates
  358. - `worker` - Active worker count changes
  359. - `reviewWorker` - Review worker status updates
  360. - `log` - New progress log entries
  361. - `heartbeat` - Keep-alive (every 15s)
  362. ## Architecture
  363. ![Claude Swarm Architecture](assets/architecture.png)
  364. *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.*
  365. ## MCP Tools Reference
  366. ### Core Orchestration (3 tools)
  367. | Tool | Description |
  368. |------|-------------|
  369. | `orchestrator_init` | Start session with task and features |
  370. | `orchestrator_status` | Get current state (use after compaction) |
  371. | `orchestrator_reset` | Clear state and kill all workers |
  372. ### Worker Management (9 tools)
  373. | Tool | Description |
  374. |------|-------------|
  375. | `start_worker` | Launch worker for a feature |
  376. | `start_parallel_workers` | Launch multiple workers simultaneously |
  377. | `start_ralph_loop` | Launch worker with Ralph Loop (fresh context per iteration) |
  378. | `validate_workers` | Pre-flight validation before parallel execution |
  379. | `check_worker` | Get worker output (supports heartbeat mode) |
  380. | `check_all_workers` | Check all active workers at once |
  381. | `send_worker_message` | Send instructions to running worker |
  382. | `configure_plan_mode` | Enable/configure worker plan-before-implement mode |
  383. | `configure_ralph_loop` | Enable/configure Ralph Loop execution defaults |
  384. ### Competitive Planning (3 tools)
  385. | Tool | Description |
  386. |------|-------------|
  387. | `get_feature_complexity` | Analyze complexity score |
  388. | `start_competitive_planning` | Spawn 2 planners with different approaches |
  389. | `evaluate_plans` | Compare plans and select winner |
  390. ### Confidence Monitoring (2 tools)
  391. | Tool | Description |
  392. |------|-------------|
  393. | `get_worker_confidence` | Get detailed confidence breakdown |
  394. | `set_confidence_threshold` | Configure alert threshold |
  395. ### Feature Management (6 tools)
  396. | Tool | Description |
  397. |------|-------------|
  398. | `mark_complete` | Mark feature done/failed (auto-retry) |
  399. | `retry_feature` | Reset failed feature for retry |
  400. | `run_verification` | Run tests/build commands |
  401. | `add_feature` | Add discovered work |
  402. | `set_dependencies` | Define feature dependencies |
  403. | `configure_verification` | Set pre-completion verification commands |
  404. ### Pre-Completion Verification
  405. Configure commands that workers must run before marking features complete:
  406. ```
  407. configure_verification(projectDir, commands: ["npm test", "npx tsc --noEmit"])
  408. ```
  409. Workers will run these commands and fix any errors before completion. Allowed commands include:
  410. - `npm test`, `npm run test`, `yarn test`, `pnpm test`
  411. - `npx tsc --noEmit`, `npx vitest`, `npx jest`
  412. - `pytest`, `python -m pytest`
  413. - `cargo test`, `cargo check`
  414. - `go test`, `make test`
  415. ### Session & Progress (7 tools)
  416. | Tool | Description |
  417. |------|-------------|
  418. | `get_progress_log` | View history (paginated) |
  419. | `get_session_stats` | Success rates and timing |
  420. | `pause_session` | Pause and stop all workers |
  421. | `resume_session` | Resume paused session (supports crash recovery) |
  422. | `shutdown_session` | Graceful shutdown with checkpoint |
  423. | `commit_progress` | Create git checkpoint |
  424. | `auto_orchestrate` | Hands-free orchestration until completion |
  425. ### Feature Rollback (2 tools)
  426. | Tool | Description |
  427. |------|-------------|
  428. | `rollback_feature` | Restore files changed by a worker |
  429. | `check_rollback_conflicts` | Check for conflicts with other workers |
  430. ### Post-Completion Reviews (5 tools)
  431. | Tool | Description |
  432. |------|-------------|
  433. | `run_review` | Manually trigger code/architecture reviews |
  434. | `check_reviews` | Monitor review worker status |
  435. | `get_review_results` | Get aggregated findings (summary/detailed/json) |
  436. | `configure_reviews` | Set auto-review preferences |
  437. | `implement_review_suggestions` | Convert review findings into features |
  438. ### Repository Setup (3 tools)
  439. | Tool | Description |
  440. |------|-------------|
  441. | `setup_analyze` | Analyze repo freshness and missing configs |
  442. | `setup_init` | Initialize repo configuration with parallel workers |
  443. | `setup_status` | Check setup progress |
  444. ### Protocol Management (5 tools)
  445. | Tool | Description |
  446. |------|-------------|
  447. | `protocol_register` | Register a new protocol |
  448. | `protocol_activate` | Activate protocol for enforcement |
  449. | `protocol_deactivate` | Deactivate protocol |
  450. | `protocol_list` | List all registered protocols |
  451. | `protocol_status` | Get protocol details and violations |
  452. ### Protocol Enforcement (4 tools)
  453. | Tool | Description |
  454. |------|-------------|
  455. | `validate_feature_protocols` | Check if feature can run under active protocols |
  456. | `get_violations` | Get recorded violations (paginated) |
  457. | `resolve_violation` | Mark violation as resolved |
  458. | `get_audit_log` | Get protocol audit history |
  459. ### LLM Protocol Generation (5 tools)
  460. | Tool | Description |
  461. |------|-------------|
  462. | `get_base_constraints` | View immutable base constraints |
  463. | `propose_protocol` | Submit a protocol proposal |
  464. | `review_proposals` | List pending proposals with risk scores |
  465. | `approve_protocol` | Approve a protocol proposal |
  466. | `reject_protocol` | Reject a protocol proposal |
  467. ### Protocol Networking (4 tools)
  468. | Tool | Description |
  469. |------|-------------|
  470. | `export_protocols` | Export protocols to shareable bundle |
  471. | `import_protocols` | Import protocols from bundle |
  472. | `sync_protocols` | Sync with peer instances |
  473. | `discover_protocols` | Discover peer MCP instances |
  474. ### Context Management (4 tools)
  475. | Tool | Description |
  476. |------|-------------|
  477. | `enrich_feature` | Auto-enrich feature with relevant docs and code |
  478. | `set_feature_context` | Manually set feature context |
  479. | `get_feature_graph` | View feature dependency graph with context |
  480. | `route_feature` | Configure worker routing preferences |
  481. ## Files Created
  482. ```
  483. your-project/
  484. ├── .claude/orchestrator/
  485. │ ├── state.json # Session state
  486. │ ├── feature_list.json # Feature status
  487. │ ├── protocols/
  488. │ │ ├── registry.json # Protocol definitions
  489. │ │ ├── active.json # Active protocols
  490. │ │ ├── violations.json # Violation records
  491. │ │ ├── audit.json # Audit log
  492. │ │ └── proposals/ # Pending proposals
  493. │ ├── sync/ # Cross-instance sync
  494. │ ├── checkpoints/ # Session checkpoints for crash recovery
  495. │ │ └── *.json # Timestamped state snapshots
  496. │ ├── heartbeat.json # Orchestrator liveness detection
  497. │ ├── learnings.json # Failure pattern learning
  498. │ ├── locks/ # File-based mutual exclusion
  499. │ │ └── *.lock # Per-file lock files
  500. │ ├── worktrees/ # Git worktree directories
  501. │ └── workers/
  502. │ ├── *.prompt # Worker prompts
  503. │ ├── *.log # Worker output logs
  504. │ ├── *.done # Completion markers
  505. │ ├── *.status # Worker status
  506. │ ├── *.plan.json # Competitive plans
  507. │ ├── *.confidence # Self-reported confidence
  508. │ ├── *.worker-plan.json # Worker plan-phase output
  509. │ ├── *.plan-done # Plan phase completion markers
  510. │ ├── *.progress.md # Ralph Loop progress files
  511. │ ├── code-review.findings.json # Code review results
  512. │ └── architecture-review.findings.json # Architecture review results
  513. ├── claude-progress.txt # Human-readable log
  514. └── init.sh # Environment setup
  515. ```
  516. ## Configuration
  517. | Variable | Default | Description |
  518. |----------|---------|-------------|
  519. | `DASHBOARD_PORT` | `3456` | Dashboard HTTP port |
  520. | `ENABLE_DASHBOARD` | `true` | Set to `false` to disable |
  521. ## Security
  522. ### Input Validation
  523. - **Path traversal protection** - All file paths validated against project directory
  524. - **Cryptographically secure IDs** - Uses `crypto.randomUUID()`
  525. - **Symlink escape prevention** - Real paths validated before file operations
  526. - **Input validation** - All inputs validated with Zod schemas
  527. ### Regex Safety (ReDoS Protection)
  528. - **Pattern validation** - `isDangerousRegexPattern()` detects catastrophic backtracking
  529. - **Safe regex testing** - `safeRegexTest()` falls back to literal matching for dangerous patterns
  530. - **Glob-to-regex conversion** - Proper metacharacter escaping prevents injection
  531. ### Memory Safety
  532. - **Bounded collections** - Operation counts, alerts, and observed patterns have maximum limits
  533. - **LRU eviction** - Least-recently-used entries removed when limits reached (max 50 cached managers)
  534. - **Timestamp truncation** - Historical data pruned to prevent unbounded growth
  535. ### Network Safety
  536. - **Localhost-only CORS** - Dashboard only accepts requests from localhost origins
  537. - **No external network access** - Workers operate in isolated tmux sessions
  538. ### Execution Safety
  539. - **Fail-closed enforcement** - Unknown constraint types block by default
  540. - **Command allowlist** - Only safe verification commands allowed
  541. - **No shell injection** - Uses `execFile` with arguments, prompts via files
  542. - **Circuit breaker pattern** - Monitor auto-stops after repeated failures
  543. - **Review worker isolation** - Read-only tools (no Bash access)
  544. ### Protocol Security
  545. - **Base constraints** - Immutable security rules cannot be overridden
  546. - **Proposal validation** - LLM-generated protocols checked against security boundaries
  547. - **Token-based matching** - Tool prohibition uses exact token matching, not substring
  548. ## Inspiration
  549. - [Anthropic's "Effective harnesses for long-running agents"](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
  550. - [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)
  551. - [Claude Code Agent Teams](https://code.claude.com/docs/en/agent-teams)
  552. - [MAKER: "Solving a Million-Step LLM Task with Zero Errors"](https://arxiv.org/abs/2511.09030)
  553. - [Multi-Agent Collaboration via Evolving Orchestration](https://arxiv.org/abs/2505.19591)
  554. - [AFlow: Automatic Workflow Optimization](https://arxiv.org/abs/2410.10762)
  555. - [AgentsNet: Coordinating Multi-Agent Networks](https://arxiv.org/html/2507.08616v1)
  556. ## Troubleshooting
  557. ### "No active session"
  558. Run `orchestrator_status` to check state, or `orchestrator_init` to start fresh.
  559. ### Worker seems stuck
  560. 1. `check_worker(featureId)` to see current output
  561. 2. `get_worker_confidence(featureId)` to check confidence score
  562. 3. `send_worker_message(featureId, "guidance")` to provide direction
  563. 4. If truly stuck, `mark_complete(featureId, success: false)` triggers auto-retry
  564. ### Lost context after compaction
  565. Call `orchestrator_status(projectDir)` - the MCP server maintains all state externally.
  566. ### Feature has unmet dependencies
  567. 1. Check dependencies with `orchestrator_status`
  568. 2. Complete dependency features first
  569. 3. Or use `set_dependencies` to modify the chain
  570. ### Protocol violations blocking work
  571. 1. `get_violations()` to see what was violated
  572. 2. `resolve_violation(violationId, resolution)` if false positive
  573. 3. Adjust protocol constraints if too restrictive
  574. ### Debugging tmux sessions
  575. ```bash
  576. # List all worker sessions
  577. tmux list-sessions | grep cc-worker
  578. # Attach to a worker session
  579. tmux attach -t cc-worker-feature-1-abc123
  580. # Capture recent output
  581. tmux capture-pane -t <session-name> -p -S -100
  582. ```
  583. ### Session crashed, how to recover
  584. 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.
  585. ### Worker keeps failing verification
  586. 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.
  587. ### Plan mode is too slow
  588. 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.
  589. ### Monitor stops unexpectedly
  590. The monitor auto-stops after 5 consecutive errors (circuit breaker). Check MCP server logs and restart if needed.
  591. ## Limitations
  592. - Requires tmux (WSL on Windows)
  593. - Workers use your Claude Code subscription
  594. - Protocol enforcement is observational (monitors but doesn't intercept tool calls)
  595. - Complex feature detection is heuristic-based
  596. ## Contributing
  597. Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
  598. ## License
  599. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.