Agent Coordinator

Agent Coordinator is the control plane for multi-agent software work.

It answers the questions that every serious agent team eventually hits:

• Who is working right now?
• On what task?
• With what mission?
• Which files or modules do they plan to touch?
• Is it safe for me to continue, review, or take over?

This repo starts from a small MCP server and grows toward a full multi-agent coordination layer for coding teams.

Product thesis

Strong coding agents do not fail only because they lack reasoning. They also fail because they lack shared operational state.

Without coordination, multiple agents:

• duplicate work
• edit the same area at once
• leave vague handoffs
• lose track of blockers
• make humans guess who owns what

Agent Coordinator exists to make multi-agent execution feel normal, reliable, and commercially useful.

What "good" looks like

In the ideal flow, every agent session has four visible steps:

1. Announce presence and mission.
2. Claim a workset before editing.
3. Leave structured checkpoints, blockers, and handoffs.
4. Hand work off or close the session cleanly.

The next agent should not need to guess. It should know:

• who was here before
• what they were trying to do
• what they touched
• what is still blocked
• whether it is safe to continue

Current status

The current implementation includes:

• actor registry (auto-registered on session start)
• session v2 with heartbeat, stale/terminal enforcement
• workset claims: project-scoped with conflict severity
• handoff v2: ownership-enforced accept/complete/cancel lifecycle
• assignment model with priority routing, accept/complete lifecycle
• agent inbox: handoffs + assignments in one call
• watch model: target-aware subscriptions (project/node/claim/actor) with eventTypes filtering
• notifications: event-aware fanout for handoffs, assignments, conflicts, stale expiries
• notification read-state: mark_notification_read, mark_all_notifications_read
• team status: compact operational summary with alerts
• activity feed with consistent project filtering
• memory bridge: deterministic mapping layer from coordinator events to Agent Memory descriptors (15 event types)
• memory recorder: live recording of coordinator events into Agent Memory with pluggable writer, node resolver, fail-open policy, and actor provenance
• memory runtime: production wiring with LocalMemoryWriter (JSONL to .agent-memory/) and CoordinatorNodeResolver
• boot overlay: coordinator state snapshot for agent startup — who is active, what is claimed, what is waiting, what is risky, what can I take over
• end-to-end resume demo: proven two-actor handoff/resume with safe claim ownership transfer and durable memory evidence
• cross-vendor resume benchmark: symmetric Claude↔Codex resume with call counts, guarantees, and limitations
• merge-risk heuristics: directory overlap, test-surface overlap, and semantic module coupling for predictive conflict detection
• predict_merge_risk: MCP tool combining heuristic engine with live coordinator state for proactive conflict assessment against active claims; emits merge_risk_predicted activity
• multi-project registry: auto-registered on all write paths (sessions, claims, handoffs, assignments), explicit registration via register_project
• cross-project actor view: get_actor_projects shows where an actor is active, blocked, or overloaded across repos
• consistent actor identity: actors auto-registered on all write paths so get_actor_projects never returns null for active participants
• coordination metrics: quantitative ROI signals — conflicts detected, handoff acceptance/completion rates, assignment pickup, stale work, pickup latency, per-project breakdown, human-readable highlights
• team control plane demo: proven 3-agent + 1-human scenario with merge-risk prevention, human reassignment, handoff pickup, and durable memory evidence
• MCP server v0.5 with 37 tools (369 tests passing)

Phases 1-6 complete. The module is ready for design-partner adoption.

Quickstart

npm install
npm run build
npm test          # 369+ tests
npm run smoke     # build + team demo

Wire into your MCP client by pointing at dist/server.js:

{
  "mcpServers": {
    "agent-coordinator": {
      "command": "node",
      "args": ["/path/to/agent-coordinator/dist/server.js"]
    }
  }
}

Full setup instructions: docs/INSTALL.md

Docs

• docs/INSTALL.md - install and quickstart guide
• docs/RELEASE.md - release workflow and checklist
• docs/DEMO-TEAM-CONTROL-PLANE.md - 3-agent + 1-human demo and benchmark
• docs/DEMO-RESUME.md - two-agent handoff and resume demo
• docs/MCP-SPEC.md - tool contracts, schemas, and state model
• ROADMAP.md - product roadmap and phases
• PAIN-POINTS.md - tracked coordination failures
• docs/BACKLOG.md - implementation tasks in execution order
• docs/IDEAL-COORDINATOR.md - what the finished product should feel like

Relationship to Agent Memory

agent-memory-kit stores durable execution memory.

agent-coordinator stores live operational coordination state.

The long-term goal is:

• memory tells the next session what happened
• coordinator tells the next session who is active right now

Together they give an agent both continuity and situational awareness.

Product shape across the toolkit

The right end-state is not one app per tool.

The better model is:

• one unified toolkit app / workbench
• agent-memory as the continuity core and likely UI nucleus
• each subrepo keeping its own MCP surface, storage, tests, and domain logic

That gives the user one coherent product while preserving clean ownership in each tool repo.

Development workflow

This project uses Agent Memory (local mode via .mcp.json).

If .agent-memory/ is empty on a fresh clone, bootstrap it with:

./scripts/bootstrap-memory.ps1

Recommended workflow for future work:

1. boot_context()
2. Read README.md, ROADMAP.md, PAIN-POINTS.md, and docs/
3. If memory does not resolve an active node, run ./scripts/bootstrap-memory.ps1
4. Execute the next task from docs/BACKLOG.md
5. Record meaningful decisions and blockers in memory
6. finalize_node(summary="...")

Treat Agent Memory as mandatory, not optional. A coding session in this repo is incomplete if it changed code or product direction but did not leave memory updates behind.

Long-term promise

The real value proposition is not "more tools for agents".

It is:

"Run multiple coding agents on the same codebase without chaos."