Swarm Mcp

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

New here? Read [docs/quickstart.md](./docs/quickstart.md) first. It walks you from zero to two Claude Code sessions seeing each other in about five minutes, with the expected output at each step.

The rest of this section is a condensed reference for non-Claude hosts. For a first-run walkthrough on a local clone, see [docs/getting-started.md](./docs/getting-started.md). For the broader modular architecture this repo is growing toward, read [docs/control-plane.md](./docs/control-plane.md). Backend and consumer config lives in [docs/backend-configuration.md](./docs/backend-configuration.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 packaged skill

Mounting the MCP server makes the swarm tools available, but agents still benefit from the bundled SKILL.md workflow. If your host supports installable skills (Claude Code, OpenCode, Codex with skills, etc.), install [skills/swarm-mcp](./skills/swarm-mcp) for coordination. 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 ../../.agents/skills/swarm-mcp .claude/skills/swarm-mcp

Or install globally for all projects:

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

Then invoke /swarm-mcp planner, /swarm-mcp implementer, etc., when starting role-specialized sessions. Full per-host install paths and copy-based alternatives live in [docs/install-skill.md](./docs/install-skill.md).

Further reading

• [docs/getting-started.md](./docs/getting-started.md) -- beginner-friendly setup and verification walkthrough
• [docs/control-plane.md](./docs/control-plane.md) -- modular agent workspace control-plane contracts and golden path
• [docs/backend-configuration.md](./docs/backend-configuration.md) -- consumer config layers, spawner/backend selection, and future swarm-server switch shape
• [docs/agent-routing.md](./docs/agent-routing.md) -- runtime-agnostic doctrine for swarm peers vs native subagents
• [docs/identity-boundaries.md](./docs/identity-boundaries.md) -- work/personal launcher, config, MCP auth, and routing boundaries
• [env/](./env) -- sourceable env-file templates for work/personal launchers and configured work trackers
• [docs/install-skill.md](./docs/install-skill.md) -- host-specific install paths for the packaged swarm-mcp skill
• [docs/swarm-server.md](./docs/swarm-server.md) -- Rust daemon for swarm-ui, mobile-style pairing, PTY streaming, and LAN access
• [docs/database-contracts.md](./docs/database-contracts.md) -- swarm.db schema ownership and adoption contract
• [docs/design-batch-creation.md](./docs/design-batch-creation.md) -- shipped-feature reference for request_task_batch (atomic multi-task creation with $N deps)
• [docs/design-routine-dispatch.md](./docs/design-routine-dispatch.md) -- design for named multi-role workflows that compose request_task_batch + dispatch; not yet implemented
• [skills/swarm-mcp](./skills/swarm-mcp) -- installable coordination skill — main SKILL.md plus role references (planner, implementer, reviewer, researcher, generalist, roles-and-teams, bootstrap, coordination, cli)
• [.agents/skills](./.agents/skills) -- repo-internal skills used while developing this repository
• [integrations/hermes/](./integrations/hermes/) and [integrations/claude-code/](./integrations/claude-code/) -- runtime plugins (lifecycle, peer-lock enforcement, /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. Its core job is the coordination bus: instance identity, tasks, messages, locks, KV, and best-effort wakeups.

Spawner backends are adapters around that bus. The default adapter is herdr; swarm-ui remains available as a fallback/control-surface adapter. New terminal managers should plug in as spawner/workspace backends rather than changing the task/message/lock contract.

The Rust apps/swarm-server daemon is a separate desktop/mobile control plane. It serves swarm-ui over a local Unix socket, exposes HTTPS/WSS on port 5444 for paired clients, manages PTYs, and reads the same swarm.db. It is not required for the basic MCP setup above. The current apps/swarm-ios workstream is Herdr-bridge first so Herdr remains the universal PTY owner; swarm-server remains useful reference material and the daemon for swarm-ui. See [docs/swarm-server.md](./docs/swarm-server.md).

Control-plane overview

Source: [docs/diagrams/backend-configuration.mmd](./docs/diagrams/backend-configuration.mmd). Backend selection and workspace identity conventions are centralized in [docs/backend-configuration.md](./docs/backend-configuration.md).

---

How it works

All sessions read and write to ~/.swarm-mcp/swarm.db by default using WAL mode, auto-vacuum, and a 3s busy timeout. Bun uses bun:sqlite; Node uses better-sqlite3.

Set SWARM_DB_PATH before launching the server if you want a different database location. Work/personal identity-separated setups should use separate paths, for example ~/.swarm-mcp-work/swarm.db and ~/.swarm-mcp-personal/swarm.db; see [docs/identity-boundaries.md](./docs/identity-boundaries.md).

When you call register, the server starts a 10s heartbeat and a 5s notification poller.

Registration fields

The register tool accepts these parameters. Only directory is required.

| Field | Required | Description | |-------|----------|-------------| | directory | Yes | The live working directory for the current session. | | scope | No | Shared swarm boundary. Sessions in the same scope can see each other; different scopes are different swarms. Defaults to the detected git root, or to directory when no git root exists. Use a new scope only for a separate swarm; do not split frontend/backend inside one repo with scope. Use team: label tokens for that. | | file_root | No | Canonical base path for resolving relative file paths in lock_file and task files. Useful when disposable worktrees should share one logical file tree. | | label | No | Free-form identity text. Recommended convention: machine-readable space-separated tokens like identity:work provider:codex-cli role:planner. The identity: token should match the launcher/config root when using identity separation. The role: token is optional; if missing, the session is treated as a generalist. |

Task features

Tasks support several features for building autonomous DAG-based workflows:

| Feature | Description | |---------|-------------| | priority | Integer (default 0). Higher = more urgent. list_tasks returns tasks sorted by priority descending. Implementers can use claim_next_task to atomically claim the highest-priority compatible task. | | depends_on | Array of task IDs. A task with unmet dependencies starts as blocked and auto-transitions to open when all deps reach done. If any dependency fails, downstream tasks are auto-cancelled. | | idempotency_key | Unique string. If a task with this key already exists, request_task returns the existing task instead of creating a duplicate. Essential for crash-safe plan retries. | | parent_task_id | Optional parent task ID for tree-structured work tracking. | | review_of_task_id | Optional task ID that a review task is reviewing. Supports $N references inside request_task_batch. | | fixes_task_id | Optional task ID that a fix task addresses. Supports $N references inside request_task_batch. | | progress_summary / progress_updated_at | First-class progress fields maintained by report_progress so peers can inspect long-running work without interrupting. | | blocked_reason / expected_next_update_at | Optional progress metadata for work that is blocked or needs a follow-up heartbeat by a specific Unix timestamp. | | approval_required | If true, task starts in approval_required status and must be approved via approve_task before work begins. Use this for true approval gates, not routine code review. |

Task statuses: open, claimed, in_progress, done, failed, cancelled, blocked, approval_required.

Session resets and prompt compaction

If a host compacts context, starts a fresh window, or loses the previous bootstrap, rejoin the swarm the same way:

1. Call register again.
2. Rehydrate with bootstrap.
3. For planners, also check kv_get("owner/planner") and kv_get("plan/latest").

The durable coordination state lives in the shared database, not in repeated per-tool prompt text.

---

Auto-cleanup

| Data | TTL | | ---------------------------------------------- | ---------- | | Stale marker (no heartbeat) | 30 seconds | | Offline instance reclaim | 60 seconds | | Messages | 1 hour | | Completed/failed/cancelled tasks | 24 hours | | Events | 24 hours | | Orphaned progress/ + plan/ KV | 1 hour |

When a session reaches the offline reclaim window, claimed or in-progress tasks are released back to open and that session's file locks are removed.

File locks stay exclusive and are cleared when the owning instance is reclaimed offline, deregisters, or completes the owning task.

Run swarm-mcp cleanup --dry-run --json to inspect what the janitor would remove without mutating the shared database.

---

Tools

Instance registry

| Tool | Description | | ----------------- | -------------------------------------------------------------------------------------------------------------------- | | register | Join the swarm. Starts heartbeat + notification poller. See [Registration fields](#registration-fields). | | deregister | Leave the swarm gracefully. Releases tasks and locks. | | bootstrap | Yield-checkpoint read for current instance, peers, unread messages, tasks, and configured work tracker metadata. | | swarm_status | Compact coordination summary: peers, unread messages, assigned/claimable tasks, locks, warnings, planner ownership, and suggested next action. | | list_instances | List all live instances. | | remove_instance | Forcefully remove another instance. Releases its tasks and locks. | | whoami | Get this instance's swarm ID. |

Messaging

| Tool | Description | | ------------------- | -------------------------------------------------------------------------------------------------------------- | | send_message | Send a direct message to a specific instance by ID. | | prompt_peer | Send a durable swarm message, then best-effort wake the target's workspace handle. Busy handles are not interrupted unless forced. | | peek_peer | Read recent or visible terminal text from a target's published workspace handle when the backend supports it. | | resolve_workspace_handle | Map a transport-local workspace handle, such as a herdr pane, back to a swarm instance ID. | | broadcast | Message all other instances in the swarm. | | poll_messages | Read unread messages and mark them as read. | | wait_for_activity | Block until new messages, task changes, KV changes, or instance changes arrive. Use only while actively monitoring a peer/dependency/review/lock, not as a generic idle loop. |

Task delegation

| Tool | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------- | | request_task | Post a task (types: review, implement, fix, test, research, other). Use review for routine code review handoff. Supports priority, depends_on, idempotency_key, parent_task_id, review_of_task_id, fixes_task_id, and approval_required. | | request_task_batch | Create multiple tasks atomically in a single transaction. Supports $N references (1-indexed) for dependencies, parent links, review links, and fix links. | | dispatch | Gateway-only: create/reuse a task, wake a matching live worker, or spawn through the configured spawner backend. Ordinary workers should not call this. Pass completion_wait_seconds only when the caller wants to wait for terminal task completion; default dispatch returns immediately after handoff/spawn. | | claim_task | Start work on a specific task: assigns and transitions to in_progress in one call. Prevents double-claiming and blocks on unread messages until poll_messages (or explicit override). Also accepts tasks pre-assigned to you (status=claimed). | | claim_next_task | Atomically pick and claim the highest-priority compatible task. Prefers tasks pre-assigned to you, then open unassigned tasks. Optional filters support task types and overlapping files. | | report_progress | Update first-class progress fields on an in_progress task, including optional blocked_reason and expected_next_update_at. Use for multi-minute or blocked work. | | complete_task | Complete a claimed task with structured JSON result fields: summary, files_changed, tests, and followups. Prefer this over update_task when you can provide structured handoff details. | | update_task | Move a task to a terminal status (done, `failed

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Volpestyle
• Source: Volpestyle/swarm-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.