swarm

swarm-mcp

MCP server that lets multiple coding-agent sessions on the same machine discover each other and collaborate through a shared SQLite database.

Each session spawns its own swarm-mcp server process via stdio. They all share one SQLite file at ~/.swarm-mcp/swarm.db by default. No daemon needed.

GitHub

---

Quick start

If you want a first-run walkthrough, start with docs/getting-started.md. If you want the broader modular architecture this repo is growing toward, read docs/control-plane.md.

Install dependencies:

cd /path/to/swarm-mcp
bun install

Add the server to your coding agent using that host's MCP config format. Bun is the simplest dev/runtime path because the examples use bun run, but the built dist/*.js entrypoints also run under Node 20+ with better-sqlite3.

Codex (~/.codex/config.toml)

[mcp_servers.swarm]
command = "bun"
args = ["run", "/path/to/swarm-mcp/src/index.ts"]
cwd = "/path/to/swarm-mcp"

opencode (~/.config/opencode/opencode.json)

{
  "mcp": {
    "swarm": {
      "type": "local",
      "command": ["bun", "run", "/path/to/swarm-mcp/src/index.ts"],
      "enabled": true
    }
  }
}

Claude Code (~/.claude.json)

{
  "mcpServers": {
    "swarm": {
      "command": "bun",
      "args": ["run", "/path/to/swarm-mcp/src/index.ts"]
    }
  }
}

Tool names are usually namespaced by the client using the server name. Depending on the host you may see swarm_register, mcp__swarm__register, or other variants. Use whichever form your host exposes.

Call the swarm register tool first to join the swarm.

Install the bundled skills

Mounting the MCP server makes the swarm tools available, but agents still benefit from the bundled SKILL.md workflows. If your host supports installable skills (Claude Code, OpenCode, Codex with skills, etc.), install skills/swarm-mcp for coordination and skills/swarm-deepdive for forensic inspection. Symlink is recommended over copying so updates from git pull propagate automatically:

# In your consumer project root
mkdir -p .agents/skills .claude/skills
ln -s /absolute/path/to/swarm-mcp/skills/swarm-mcp .agents/skills/swarm-mcp
ln -s /absolute/path/to/swarm-mcp/skills/swarm-deepdive .agents/skills/swarm-deepdive
ln -s ../../.agents/skills/swarm-mcp .claude/skills/swarm-mcp
ln -s ../../.agents/skills/swarm-deepdive .claude/skills/swarm-deepdive

Or install globally for all projects:

mkdir -p ~/.claude/skills
ln -s /absolute/path/to/swarm-mcp/skills/swarm-mcp ~/.claude/skills/swarm-mcp
ln -s /absolute/path/to/swarm-mcp/skills/swarm-deepdive ~/.claude/skills/swarm-deepdive

Then invoke /swarm-mcp planner, /swarm-mcp implementer, etc., when starting role-specialized sessions, or /swarm-deepdive for investigations. Full per-host install paths and copy-based alternatives live in docs/install-skill.md.

Further reading

• docs/getting-started.md -- beginner-friendly setup and verification walkthrough
• docs/control-plane.md -- modular agent workspace control-plane contracts and golden path
• docs/agent-routing.md -- runtime-agnostic doctrine for swarm peers vs native subagents
• docs/identity-boundaries.md -- work/personal launcher, config, MCP auth, and routing boundaries
• docs/install-skill.md -- host-specific install paths for the bundled skills
• docs/swarm-server.md -- Rust daemon for desktop UI, mobile pairing, PTY streaming, and LAN access
• docs/database-contracts.md -- swarm.db schema ownership and adoption contract
• docs/design-batch-creation.md -- design spec for request_task_batch
• skills/swarm-mcp -- installable coordination skill — main SKILL.md plus role references (planner, implementer, reviewer, researcher, generalist, roles-and-teams, bootstrap, coordination, cli)
• skills/swarm-deepdive -- installable forensic inspection skill source
• integrations/hermes/ and integrations/claude-code/ -- runtime plugins (lifecycle, lock bridge, /swarm slash command)

---

MCP server vs swarm-server

The TypeScript swarm-mcp process is the stdio MCP server used by coding-agent hosts. It is enough for local multi-agent coordination through tools, resources, prompts, and the shared SQLite database.