Zero conflicts. Every agent aligned.
5 agents, 1 codebase, 0 merge conflicts. The MCP server that keeps parallel Claude Code, Cursor, and Cline agents aligned.
The coordination pain
Parallel agents without shared awareness produce three failure modes that ship to production.
Silent regressions
Tuesday 3pm. Alice's agent ships User.updated_at. Four minutes later, Bob's agent renames User.id. Tests pass. Prod breaks at 2am because the migration order was wrong.
Duplicated effort
Two agents both implement retry logic. Agent A picks exponential backoff (250ms→8s). Agent B picks linear (500ms, 5 retries). Code review surfaces the divergence — 800k tokens in.
No visibility
Tom asks his agent: “is anyone else working on auth?” The agent answers: “I have no way to know.” Tom shrugs and proceeds. Carol's agent did the same thing 20 minutes ago.
See it run live
Four agents stay aligned in real time without chat tools, merge gymnastics, or shared spreadsheets.
Conflicts caught before code is written
Every announcement reaches every concerned agent before they open a file. Overlaps surface as a paused turn, not a midnight rollback.
How it works
Four steps run before any code is written, then a score decides who consults.
Announce
The agent declares intent: task, target files, affected modules. No code yet.
Detect
The scorer checks every active announcement across six layers and returns a 0-to-100 impact score.
Consult
The coordinator opens a consultation thread and publishes it to the MQTT broker. Each concerned agent reads the event between turns and posts context, constraints, or a resolution. No sidecar process required.
Resolve
Proposals are approved, contested, or re-proposed. The thread closes on consensus. Every decision lands on the dashboard timeline.
Impact score
Every announcement is scored 0 to 100 against active work. The score decides the response.
Six layers, most severe wins. Full details on GitHub →
In-flight awareness v0.5
Hook-based PreToolUse + PostToolUse hooks let the coordinator see agents start editing files — not just when they finish. Conflicts surface before bytes are written, not after.
Symbol-aware scoring v0.3+
tree-sitter parses 15 languages (TS/TSX/JS/JSX/Python/Go/Rust/Java/C#/C/C++/Ruby/PHP/Kotlin/Swift/Bash). Two agents editing the same file but different functions get an annotated reason — not a silent block.
Git co-change scoring v0.5
Files that move together in git history (config + consumer, fixture + test) are scored as related: impact 60 if >50% co-change, 40 if >20%. Catches regressions invisible to filename matching.
Real-time push: MQTT topics and delivery flow
An embedded MQTT broker fans every event to subscribers. Eight topics, end-to-end latency under 50ms.
| Topic | Emitted when | Key payload |
|---|---|---|
coordinator/consultations/new |
A thread is opened | thread_id, subject, initiator_id, target_files |
.../consultations/+/messages |
Someone posts to a thread | agent_id, name, content, type |
.../consultations/+/status |
Thread transitions state | status: open/resolving/resolved/timeout |
.../consultations/+/claimed |
Work-stealing claim (atomic) | claimed_by, thread_id |
.../consultations/+/completed |
Claimed task finishes | agent_id, thread_id, resolution |
coordinator/agents/+/status |
Agent online / offline | status, name, modules |
coordinator/broadcast |
System-wide announcement | arbitrary JSON |
coordinator/quota/update |
Anthropic quota refresh | usage, limit, utilization_pct |
Push delivery flow
Coordination patterns
Four coordination shapes the protocol supports natively. Build them with the 26 MCP tools.
All agents start at once. The coordinator opens a consultation thread the moment two announcements overlap.
[A] [B] [C] [D] | | | | A & C overlap on types.ts → consultation
Agents work in declared order. Each one consumes the prior agent's output before announcing its own work.
[A] → [B] → [C] spec code test handoff between turns
A lead agent splits the mission and dispatches subtasks. Subordinates announce work, consult, and report back.
[lead] / | \ [A] [B] [C] ↑ ↑ ↑ report results
Observer agents watch the timeline. They post warnings or comments without ever announcing their own work.
[A] [B] [C] | | | [obs] reads timeline → posts comment or warning
Wire these patterns yourself via mcp-coordinator's 26 MCP tools — or skip the boilerplate with essaim's pre-built catalog. See essaim's catalog →
Why not alternatives?
Worktrees, lockfiles, CI, orchestrators — none of them know your agent's intent.
…git worktrees?
No. Worktrees isolate filesystems. mcp-coordinator coordinates intent. A clean merge of two incompatible designs still ships a broken runtime. Use both.
…Claude Code subagents?
Subagents coordinate inside one Claude Code session. mcp-coordinator coordinates any MCP client across any session, machine, or vendor. Cursor and Claude Code on different laptops can share one consultation thread.
…Slack and manual coordination?
Slack works because humans read it. Your agent doesn't. mcp-coordinator lets the agent itself ask "is anyone touching this file?" before writing — at a cost of a few milliseconds.
…CI gates and branch protection?
CI catches the conflict after both agents have already burned tokens writing incompatible code. mcp-coordinator catches it before a single line is written. CI is the safety net; this is the harness.
…multi-agent orchestrators?
Orchestrators run agents; mcp-coordinator is the protocol they speak. essaim composes with mcp-coordinator natively. AutoGen and CrewAI ship without conflict detection — pair them with mcp-coordinator and they stop colliding.
npm install -g mcp-coordinator
Install in one command
Architecture & deployment
One agent-loop per developer, one coordinator serving MCP, MQTT, and the dashboard, same shape from laptop to cloud.
The shape of a coordinated session
agent-loop
MCP + MQTT + SSE
agent-loop
TCP 1883 / WS /mqtt
SSE events :3100/dashboard
Agent-loop
A programmatic loop wrapping the Claude CLI (spawn-per-turn claude -p --resume). Holds the MQTT listener, the protocol state machine, and the work-stealing claim logic. Use essaim's loop, or roll your own.
mcp-coordinator server
A Node.js process exposing 26 MCP tools over HTTP/SSE, with the embedded Aedes MQTT broker. SQLite stores threads, agents, and the dependency map. Anthropic quota is pre-flighted before multi-agent runs.
Dashboard
A live SSE stream at localhost:3100/dashboard. Per-agent activity, scoring breakdown, quota widget, decision timeline, and the v0.5 "Conflict signals" panel showing per-layer firing counts over the last 24 h. No auth in local mode; JWT-gated for cloud.
Three modes, one experience
Local mode
The coordinator, broker, and dashboard run on your machine. Best for solo work or trying mcp-coordinator before bringing teammates in.
agent-loop
:3100
Aedes · :1883 / /mqtt
:3100/dashboard
mcp-coordinator server start --daemonTeam server
One coordinator on a shared LAN machine. Every developer's agent-loop connects to the same instance. Every announcement, every consultation, visible to the whole team.
agent-loop
coordinator :3100
MQTT :1883 / /mqtt
dashboard /dashboard
agent-loop
agent-loop
mcp-coordinator init ~/project --url http://192.168.x.x:3100 --name "Alice"Cloud hosted
Self-hosted on a VM or container. Remote teams coordinate through one TLS endpoint, with WebSocket MQTT on port 443. JWT-gated.
agent-loop
coordinator + Aedes
WS /mqtt on 443
TLS + JWT auth
agent-loop
agent-loop
mcp-coordinator init ~/project --name "Alice" --url https://coordinator.team.comGet started
Self-hosted from one npm package — embedded broker and dashboard, no cloud, ready in under a minute.
Install
One npm package. No separate broker, no database to provision.
First-time setup
Creates the config directory, writes a default config.json, and prints the .mcp.json snippet for your MCP client (Claude Code, Cursor, Cline). Add --write-mcp-config <path> to merge the snippet straight into a project's .mcp.json.
Start the server
Boots the MCP server, embedded MQTT broker, and dashboard on localhost:3100. --daemon backgrounds the process and writes logs to the config directory.
Verify and open
The doctor command checks config, server, MCP responses, and MQTT connections, then opens the dashboard at localhost:3100/dashboard.
git worktree add ../feature-x main and run each agent in its own worktree — mcp-coordinator handles "who's editing types.ts"; worktrees handle "no two agents fighting the same inode."
What you'll see in 60 seconds
Tested coordination scenarios
Four canonical conflict patterns, each run end-to-end with two real agents to verify score, thread state, and resolution.
| Scenario | Description | Score | Outcome |
|---|---|---|---|
| S1 | Two agents announce work on the same file at the same moment | 100 | Consultation thread opens, both agents post context, consensus reached, both proceed |
| S2 | Two agents announce work inside the same feature module | 30 | Auto-resolved, both agents notified for awareness |
| S3 | Agent A's module depends on Agent B's current output | 80 | Dependency flagged, dependent agent waits or replans |
| S4 | Fully independent tasks, no shared files or modules | 0 | No conflict detected, both agents proceed in parallel |
FAQ
Quick answers to common questions about coordination, deployment, and integration.
Does this replace git worktrees?
Is it production-ready?
doctor command, structured Pino logs.What does it cost?
Which MCP clients work?
Can multiple repos share one coordinator?
Is auth or JWT required?
How is this different from Aider or Cline's own coordination?
Yet another tool to maintain?
npm install -g. Embedded MQTT broker, SQLite, and dashboard ship in the package. Zero sidecar. Symmetric uninstall reverses the init actions; --purge wipes the data dir.What if the coordinator goes down?
Will my agent lose context between turns?
Which programming languages does conflict detection support?
How does conflict detection work under the hood?
Roadmap
Shipped, in flight, and what comes after.
v0.1 — Server extraction
26 MCP tools, embedded Aedes broker, SQLite state, real-time dashboard. Standalone npm package.
v0.2 — Standalone autonomy
First-run init, doctor diagnostics, daemon log tailing via server logs, symmetric uninstall. Vanilla MCP clients (Claude Code, Cursor, Cline) coordinate via polling out of the box. essaim's agent-loop adds push.
v0.3 — Semantic conflict detection
AST-level analysis on top of filename scoring via tree-sitter. Detects API contract changes and interface incompatibilities before a thread opens. Symbol-aware scoring: same file, different functions = annotated reason, not a silent block. 15 languages supported (TS/TSX/JS/JSX/Python/Go/Rust/Java/C#/C/C++/Ruby/PHP/Kotlin/Swift).
v0.4 — Dashboard redesign & operability
Full landing page and dashboard redesign. New "Conflict signals" panel with per-layer firing counts over the last 24 h. Extended /readyz with tree_sitter and git_cochange health blocks. 5 new Prometheus metrics, 8 new env vars / CLI flags, PRAGMA user_version downgrade guard, and 413 body-size cap.
v0.5 — In-flight awareness & git co-change
Hook-based PreToolUse + PostToolUse: the coordinator sees agents start editing, not just finish. Git co-change scoring: files that share commit history (config + consumer, fixture + test) get impact score 60 if >50% co-change, 40 if >20%. 392-test suite across 46 files.
LLM Reasoner — gray-zone arbitration (opt-in)
A gated, opt-in layer that sends ambiguous gray-zone conflicts to a small LLM for structured arbitration. Design phase — will ship after one month of v0.5.0 telemetry confirms the ROI justifies the latency trade-off.
v1.0 — Stable API + cross-repo coordination
Frozen public API, versioned REST endpoints, migration guides. Coordination across multiple repositories from a single MQTT broker.
Server-gated push (when available)
Native integration with Anthropic's forthcoming server-side push channel (internally tracked as tengu_harbor). Listener code already lives alongside the MQTT bridge. The moment it ships, mcp-coordinator plugs in.