Repolode
Submit
cj-vana

cj-vana/claude-swarm

An MCP server that orchestrates parallel Claude Code worker swarms in tmux and git worktrees, with protocol-based behavioral constraints and a live dashboard.

View on GitHub
Stars
117
Forks
10
Open issues
0
Last commit
8 months ago

What is it?

Claude Swarm is an MCP server that lets a Claude Code session act as an orchestrator for multiple Claude Code workers. Each worker runs in its own tmux session inside an isolated git worktree, implements one feature, and reports status back. The server keeps session state on disk so work can survive context compaction, crashes, and machine restarts through checkpoints and heartbeat-based recovery.

The project adds a few mechanisms for long-running autonomous coding. Workers can go through a read-only plan phase before implementing, complex features can get competitive plans, and a Ralph Loop launches a fresh Claude session per iteration with progress persisted to files. Verification commands must pass before a feature is marked complete, failed features can retry automatically, and post-completion code and architecture reviews produce structured findings.

Protocols define behavioral constraints such as tool restrictions, file access rules, and resource limits. They are checked before a worker starts and monitored during execution, with violations logged for review. A web dashboard at localhost:3456 streams worker terminal output and session progress over Server-Sent Events.

Key features

  • 01Runs parallel Claude Code workers in tmux sessions, each in its own git worktree.
  • 02Persists session state and checkpoints so work resumes after crashes or restarts.
  • 03Runs a two-phase plan-then-implement lifecycle for complex features.
  • 04Enforces verification commands before features are marked complete, with automatic retries.
  • 05Defines behavioral protocols that are validated before and monitored during worker execution.
  • 06Provides a real-time web dashboard with live terminal output.

Use cases

  • Splitting a large feature set, such as a REST API with auth and tests, across parallel coding agents.
  • Running multi-hour autonomous coding sessions that need to survive interruptions.
  • Restricting what autonomous coding agents can access or run through explicit protocols.
  • Monitoring several agent workers at once from a browser dashboard.

Quick start

  1. 1

    Install prerequisites: Node.js 18+, tmux, Claude Code CLI

  2. 2

    One-liner install (clones, builds, registers MCP server, installs skill)

    Install with the official instructions in the README
  3. 3

    Or manual: clone, install dependencies, build

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

    Register the MCP server with Claude Code

    claude mcp add claude-swarm --scope user -- node $(pwd)/dist/index.js

Things to know

  • Requires tmux and the Claude Code CLI installed alongside Node.js 18+.
  • Orchestrates Claude Code workers, so it is tied to that tool and its usage costs.

Topics

#ai-agents#claude#mcp#orchestration#tmux#typescript#git-worktree

FAQ

What is claude-swarm?
An MCP server that orchestrates parallel Claude Code worker swarms in tmux and git worktrees, with protocol-based behavioral constraints and a live dashboard. Claude Swarm is an MCP server that lets a Claude Code session act as an orchestrator for multiple Claude Code workers. Each worker runs in its own tmux session inside an isolated git worktree, implements one feature, and reports status back. The server keeps session state on disk so work can survive context compaction, crashes, and machine restarts through checkpoints and heartbeat-based recovery.
Is claude-swarm free to use? What license does it have?
claude-swarm is open source under the MIT license. Check the license terms before using it in commercial products.
Is claude-swarm still maintained?
No commits for 6+ months. The last commit to claude-swarm was on Feb 11, 2026.
What can I use claude-swarm for?
Splitting a large feature set, such as a REST API with auth and tests, across parallel coding agents. Running multi-hour autonomous coding sessions that need to survive interruptions. Restricting what autonomous coding agents can access or run through explicit protocols. Monitoring several agent workers at once from a browser dashboard.
How do I install claude-swarm?
Install prerequisites: Node.js 18+, tmux, Claude Code CLI One-liner install (clones, builds, registers MCP server, installs skill) Or manual: clone, install dependencies, build: git clone https://github.com/cj-vana/claude-swarm.git && cd claude-swarm && npm install && npm run build Register the MCP server with Claude Code: claude mcp add claude-swarm --scope user -- node $(pwd)/dist/index.js
Where can I get claude-swarm?
The source code and installation instructions are on GitHub: https://github.com/cj-vana/claude-swarm

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects