Project Status (May 2026): Development is now paused. This will be the final major update. See the retrospective below.
Stop AI coding assistants from overwriting each other's work.
When you let multiple AI assistants help on the same project, they can accidentally undo each other's edits — one rewrites a file while another is still working on it. CoordinationHub is a shared notice-board that tracks who's editing what, and stops two assistants from touching the same file at once. Live dashboard included.
Runs locally on your machine. No Docker, no external services, no API keys to manage.
For developers: small MCP server, pure Python stdlib, zero third-party dependencies. Works with Claude Code's hooks out of the box; compatible with any MCP client.
Note: As of May 2026, active development has been paused. The project remains useful for heavy multi-agent workflows with weaker agent systems (especially Claude Code).
The web dashboard at http://127.0.0.1:9898 (above) shows the agent tree, task registry, work intent board, handoffs, dependencies, and active locks live — fed by the same SQLite store the hooks write to. Drag to pan, mouse-wheel to zoom.
CoordinationHub is no longer being actively developed.
This project was created because of a very specific and painful problem observed while using Claude Code with many sub-agents on complex, long-running projects:
Sub-agents would repeatedly overwrite or “fix” work that other sub-agents had already done. This created cycles of rework, lost progress, and significantly extended project timelines. The core issues were lack of visibility into who was working on what, weak file ownership, and no good way for one agent to leave useful context for others.
CoordinationHub was built to mitigate this through:
- Explicit document locking (including region-level locking)
- Agent identity, lineage, and live status tracking
- Shared task registry and dependency management
- The ability for agents to leave coordination notes for each other
- A live dashboard for situational awareness
It served its purpose well during a period when many agent systems (especially Claude Code) produced relatively weak sub-agents that frequently conflicted with each other.
As of mid-2026, the rapid improvement in model capability — particularly with Grok — has meaningfully reduced this specific problem. Stronger, faster agents with better reasoning quality mean that heavy external coordination tooling is no longer as necessary for many real-world workflows.
This will be the final major update to CoordinationHub. The repository will remain available for anyone who still works with weaker or more fragmented multi-agent setups and needs explicit coordination controls. The code is stable and the release process is fully automated.
I worked closely with the creator of this project during its final development phase.
CoordinationHub was a pragmatic and well-engineered response to a real limitation in how multi-agent coding systems were being used in 2026. The user didn’t build it as an academic exercise — they built it because they were personally losing large amounts of time to sub-agents undoing each other’s work.
The fact that stronger models (particularly newer versions of Grok) have reduced the severity of that problem enough for the maintainer to pause development is, in a way, a positive signal. It means the underlying models are getting better at maintaining coherence across complex, long-running tasks without needing as much external scaffolding.
That said, the core ideas behind CoordinationHub — persistent agent identity, shared file ownership awareness, contention detection, and lightweight coordination notes — remain fundamentally sound. For sufficiently complex projects involving many specialized agents, some form of coordination layer (whether external like this or built natively into the agent system) will likely remain valuable for a long time.
This project made those pain points visible and measurable. That has value beyond the code itself.
— Grok, May 2026
When three AI coding assistants help refactor the same part of your project, they'll sometimes step on each other — two of them editing the same file at once, whichever saves last wins, no warning that anything was lost. CoordinationHub is the shared whiteboard they all check before touching anything: one place that shows who's alive, who holds which file, which tasks are blocked, and where one assistant's edits are crossing into another's territory.
pip install coordinationhubFor the stdio MCP server (used by many IDEs and custom agents):
pip install coordinationhub[mcp]This also installs the coordinationhub-mcp console script (a direct entry point to the stdio server).
# One-time setup: creates the SQLite store and wires Claude Code hooks
coordinationhub init
# Optional opt-ins (recommended for multi-agent work):
coordinationhub init --auto-dashboard --monitor-skill
# --auto-dashboard installs a SessionStart hook that idempotently launches
# the dashboard at http://127.0.0.1:9898 every session.
# --monitor-skill installs a `coordinationhub-monitor` skill at
# ~/.claude/skills/ — invoke it on a Claude Code agent
# and that agent becomes a read-only swarm watcher
# (polls the dashboard, surfaces boundary crossings,
# blocked tasks, and stale agents).
# Sanity-check the install
coordinationhub doctorThat's it. From the next Claude Code session in this repo, every agent self-registers, every Write/Edit acquires a lock, every subagent shows up in the dashboard tree, and on session-end everything is cleaned up. You don't need to call any MCP tool by hand.
coordinationhub serve-sse # web dashboard (auto-started by --auto-dashboard above)
coordinationhub watch # live-refreshing terminal tree
coordinationhub agent-tree # one-shot terminal tree
coordinationhub status # JSON snapshotThe dashboard panel layout (matching the screenshot above):
| Panel | What it shows |
|---|---|
| Agent Tree | Hierarchy with parent→child edges, current task per agent, lock count, status dot. Pan + zoom controls in the corner. |
| Task Registry | Shared work board: pending / in_progress / completed / blocked, with the assigned agent and description. |
| Work Intent Board | Soft "I am about to touch this file" markers — TTL'd, non-binding, used to avoid colliding before acquiring a hard lock. |
| Handoffs | Explicit "I'm done with this scope, you take it" events with acknowledgements. |
| Agent Dependencies | "Agent X is waiting on agent Y to finish task T" — green when satisfied, red while still blocking. |
| Active Locks | Every TTL'd file lock with age, time-to-live, lock type, and a ⚠ marker when the lock crosses into another agent's owned territory. |
Every agent in the swarm sees the same hierarchy. From the terminal:
hub.cc.main [active] — "observing..."
├── hub.cc.main.0 [Agent A] — service consolidation
│ ├─ ◆ src/services/mcpProbes.js [exclusive]
│ └─ ◆ mcpChallengeRoutes.js [exclusive] ⚠ owned by hub.cc.main.1
├── hub.cc.main.1 [Agent B] — "route simplification"
│ ├─ ◆ routeLoader.js [exclusive L325-360]
│ └─ ◆ vcsRoutes.js [exclusive]
└── hub.cc.main.2 [Agent C] — data layer
├── hub.cc.main.2.0 [CA] — "working on fileStore.js"
│ └─ ◆ fileStore.js [exclusive]
└── hub.cc.main.2.1 [CB] — "working on BaseModel"
├─ ◆ BaseModel.js [exclusive]
└─ ◆ baseModel.test.js [shared]
Each node shows: agent ID, role/task, every active file lock with type and region, plus a ⚠ when the lock crosses someone else's owned territory.
- File locking with TTL, retry, and force-steal-with-conflict-log.
- Region locking — two agents can edit non-overlapping ranges of the same file.
- Scope enforcement — agents declare a path-prefix scope; out-of-scope locks are denied.
- Boundary detection — flags any lock that crosses into another agent's owned territory.
- Cascade cleanup — when an agent dies, children are re-parented to the grandparent and locks released. Nothing is orphaned.
- Agent tracking — globally unique IDs (
hub.PID.seq.seq), live hierarchy, heartbeat-based stale detection. - Change notifications — agents publish what they changed, others poll. No message bus.
- Inter-agent messaging — direct point-to-point with arbitrary JSON payloads.
- Cross-agent dependencies — auto-satisfy when the depended-on task completes.
- Contention hotspots — rank files by lock-conflict frequency.
- Dashboard — pure-SVG live view, zero JS dependencies, fed by SSE.
Define your agent roles and handoff rules once in a coordination_spec.yaml at the repo root, and scan_project / run_assessment use it to attribute file ownership and score swarm behaviour.
agents:
- id: planner
role: decompose tasks
responsibilities: [break down user stories, assign subtasks]
- id: executor
role: implement
responsibilities: [write code, run tests]
handoffs:
- from: planner
to: executor
condition: task_size < 500 && no_blockersFine without one — scan_project and run_assessment synthesise an implicit graph from live agent registrations when no spec exists.
hub.12345.0 — root agent (namespace.PID.sequence)
hub.12345.0.0 — child of root
hub.12345.0.1 — sibling
hub.12345.0.0.0 — grandchild
Several entries are meta-tools that dispatch on an action parameter (manage_messages, manage_dependencies, manage_work_intents, manage_leases, admin_locks, query_tasks, task_failures) — keeps the surface small (target ≤ 50 enforced by tests/test_tool_count.py). Full auto-generated table with descriptions is in COMPLETE_PROJECT_DOCUMENTATION.md.
| Category | Tools |
|---|---|
| Identity | register_agent, heartbeat, deregister_agent, list_agents, get_agent_relations |
| Locking | acquire_lock, release_lock, refresh_lock, get_lock_status, list_locks, admin_locks |
| Coordination | broadcast, wait_for_locks, await_agent |
| Broadcast | acknowledge_broadcast, wait_for_broadcast_acks |
| Messaging | send_message, manage_messages |
| Changes | notify_change, get_notifications |
| Audit | get_conflicts, get_contention_hotspots, status |
| Visibility | load_coordination_spec, scan_project, get_agent_status, get_file_agent_map, update_agent_status, run_assessment, get_agent_tree |
| Tasks | create_task, create_subtask, assign_task, update_task_status, query_tasks, wait_for_task, get_available_tasks, task_failures |
| Dependencies | manage_dependencies |
| Work Intent | manage_work_intents |
| Handoffs | wait_for_handoff |
| HA Leases | acquire_coordinator_lease, manage_leases |
| Spawner | spawn_subagent, report_subagent_spawned, get_pending_spawns, request_subagent_deregistration, await_subagent_registration, await_subagent_stopped, is_subagent_stop_requested |
# Setup & diagnostics
coordinationhub init [--auto-dashboard] [--monitor-skill] # one-time setup; opt-in extras
coordinationhub doctor # validate setup, detect venv issues
coordinationhub auto-start-dashboard # idempotent dashboard launcher (used by hook)
# Servers
coordinationhub serve --port 9877 # HTTP MCP + admin API
coordinationhub serve-mcp # stdio MCP (requires coordinationhub[mcp])
coordinationhub-mcp # direct stdio entry point (same as above, nicer for some launchers)
coordinationhub serve-sse --port 9898 # web dashboard with SSE stream
# See what's happening
coordinationhub status # JSON snapshot
coordinationhub dashboard # full terminal table
coordinationhub agent-tree # hierarchy
coordinationhub agent-status <id> # single agent detail
coordinationhub contention-hotspots # files with most conflicts
coordinationhub watch # live-refresh tree (Ctrl+C)
# Agent lifecycle
coordinationhub register <id> [--parent-id <parent>]
coordinationhub heartbeat <id>
coordinationhub deregister <id>
coordinationhub list-agents
coordinationhub agent-relations <id> [--mode lineage|siblings]
# File locking
coordinationhub acquire-lock <path> <id> [--region-start N --region-end N]
coordinationhub release-lock <path> <id> [--region-start N --region-end N]
coordinationhub refresh-lock <path> <id> [--region-start N --region-end N]
coordinationhub lock-status <path>
coordinationhub list-locks [--agent-id <id>]
coordinationhub admin-locks <action> # release_agent_locks | reap_expired | reap_stale_agents
# Coordination & changes
coordinationhub broadcast <id> [--document-path <path>]
coordinationhub wait-for-locks <id> <paths...>
coordinationhub notify-change <path> <type> <id>
coordinationhub get-notifications [--since T] [--exclude-agent <id>] [--limit N]
coordinationhub wait-for-notifications <id> [--timeout S] [--exclude-agent <agent>]
coordinationhub get-conflicts
# Graph & assessment
coordinationhub load-spec
coordinationhub validate-spec
coordinationhub scan-project
coordinationhub assess [--suite <file>] # without --suite scores live session
# Tasks
coordinationhub create-task <task_id> <parent_agent_id> <description>
coordinationhub assign-task <task_id> <agent_id>
coordinationhub update-task-status <task_id> <status>
coordinationhub query-tasks <action> # by_id | by_parent | by_assigned | tree
coordinationhub wait-for-task <task_id> [--timeout S]
coordinationhub get-available-tasks [--agent-id <id>]
coordinationhub task-failures <action> # retry | dlq | historyRun coordinationhub --help for the full list (74+ commands; HA leases, spawner, work intents, dependencies, handoffs).
- Region-locked release. When an agent holds a region lock,
release-lock <path> <id>(no region args) returnsreleased=false reason=region_requiredwith the activeregion_lockslisted. Re-issue with the matching--region-start/--region-endto release. Whole-file releases continue to use the no-args form. - Heartbeat decay. A registered agent only counts toward
active_agentswhile itslast_heartbeatis recent (default stale-timeout: 600 s). Long-running flows must callcoordinationhub heartbeat <id>periodically or they will drift to inactive even though the row remains in the agents table. - Notification growth.
notify-changeevents accumulate in the notifications table; runcoordinationhub prune-notifications --max-age-seconds N(or--max-entries M) periodically — there is no implicit prune on agent connect.
SQLite-backed, thread-safe, WAL mode. Every module under 500 code LOC with single responsibility. Sub-modules have zero internal cross-dependencies — they receive a connect callable from the caller. Both HTTP and stdio servers share dispatch.py and the schemas/ package.
Engineering notes (design decisions, schema versioning, hook contract, sub-agent task correlation, file ownership rules) live in CLAUDE.md. Auto-generated file inventory and full MCP tool table live in COMPLETE_PROJECT_DOCUMENTATION.md. Reverse-chronological dev log is in LLM_Development.md.
coordinationhub/
core.py + core_*.py mixins — CoordinationEngine, one mixin per capability
_storage.py — SQLite pool, path resolution, thread-safe ID generation
db.py + db_schemas.py + db_migrations.py
— connection pool, schema definitions, migration driver
lock_ops.py — lock primitives + region-overlap detection
agent_registry.py — agent lifecycle (register/heartbeat/deregister/lineage)
notifications.py — change notification storage
conflict_log.py — conflict recording + queries
scan.py / agent_status.py — file ownership scan, agent tree
schemas/ — 14 per-domain MCP tool schema modules
dispatch.py — tool dispatch table
mcp_server.py — HTTP server (stdlib http.server only)
mcp_stdio.py — stdio MCP server (optional `mcp` package)
cli.py + cli_*.py — argparse parser + per-domain command handlers
hooks/{base,claude_code,kimi_cli,cursor}.py
— IDE hook adapters
plugins/{assessment,dashboard,graph}/
— assessment runner, web dashboard, coordination graph
data/monitor_skill.md — installable Claude Code skill template
tests/ — <!-- GEN:test-count -->807<!-- /GEN --> tests across 28 files
Core uses only the Python stdlib. The mcp package is optional (stdio transport only). Air-gapped install:
pip install coordinationhub --no-depsRelease automation is also secret-free and zero-dep. Push a version tag and everything happens automatically:
git tag v0.7.10 && git push origin v0.7.10- A GitHub Release is created with the built wheel + sdist attached.
- The release triggers PyPI publication using GitHub OIDC Trusted Publishing (short-lived token minted on the fly — no API tokens are ever stored in the repo or in GitHub secrets).
- Both
release.ymlandpublish.ymldeliberately use only pre-installed tools (git,gh,python,curl) plusbuild/twineinstalled at runtime. No third-party GitHub Actions.
See RELEASING.md for the exact one-time setup (PyPI Trusted Publisher + "pypi" environment) and the full release checklist.
| Server | Default port |
|---|---|
| Stele | 9876 |
| CoordinationHub MCP | 9877 |
| CoordinationHub dashboard | 9898 |
| Chisel | 8377 |
| Trammel | 8737 |
The init command merges hooks into ~/.claude/settings.json:
- SessionStart — register the root agent, stamp its
current_taskfrom the user's prompt. - PreToolUse Write/Edit — acquire a file lock; deny if another agent holds it.
- PreToolUse Agent — stash the sub-agent's
descriptionfor FIFO correlation with the nextSubagentStart. - PostToolUse Write/Edit — fire
notify_change, release the lock so other agents don't wait for TTL expiry. - SubagentStart / SubagentStop — register/deregister children, applying the stashed task description.
- SessionEnd — release all locks, deregister the session agent.
Bridges: PostToolUse on mcp__stele-context__index fires notify_change with type "indexed"; on mcp__trammel__claim_step calls update_agent_status with the step/plan ID.
The hook script is coordinationhub/hooks/claude_code.py. It reads JSON from stdin, creates a lightweight engine per call (~5 ms), and fails open on any error so a hub problem never blocks a Claude Code session.
CoordinationHub uses a fully automated, tokenless release pipeline:
# Bump version in the single source of truth
vim coordinationhub/__init__.py # __version__ = "0.7.10"
python -m pytest tests/ -q # full suite
python scripts/gen_docs.py # regenerate GEN sections
git add coordinationhub/__init__.py AGENTS.md COMPLETE_PROJECT_DOCUMENTATION.md ...
git commit -m "chore: prepare v0.7.10"
git push origin main
git tag v0.7.10
git push origin v0.7.10The tag push triggers:
.github/workflows/release.yml— builds the package and creates a GitHub Release with the.whl+.tar.gzattached.- The Release event triggers
.github/workflows/publish.yml— publishes to PyPI using OIDC (no secrets).
Full instructions, one-time PyPI Trusted Publisher setup, and troubleshooting live in RELEASING.md.
Recent robustness work (v0.7.9) hardened the system for large concurrent swarms (22+ sub-agents, 48-broadcast storms, worktree-isolated spawns, HA coordinator leases, region locks, etc.).