dugubuyan/agent-nexus

**The coordination layer for heterogeneous LLM code agents.**
Let a backend agent, a frontend agent, and an infra agent — running on *different* IDEs and *different* models — stay in sync automatically, with zero hand-written glue.
> An MCP server that coordinates AI code agents across service boundaries.
> *(Not affiliated with the MIT Lincoln Laboratory project of the same name.)*
---
The problem
Your product isn't one codebase. It's a backend, a frontend, some infra, a test suite — each with its own repo, stack, and agent. When the backend changes its API, the frontend has to adapt. Today that coordination is done by humans copy-pasting specs into chat, or by hand-written CLAUDE.md / AGENTS.md files that go stale the moment the service changes.
Role-playing multi-agent frameworks (ChatDev, MetaGPT) don't help here: they assume all agents live in one simulated org, one codebase. Real systems are a mesh of independently-owned parts.
What AgentNexus does
AgentNexus coordinates agents at the **service boundary** — the unit real systems are actually built from. Each boundary registers as a sub-project, publishes versioned Markdown documents (requirements, design, API specs, config), and subscribes to the documents it depends on. When a document changes, subscribers get a **diff-aware notification** — the exact change plus the full latest content — so an agent can make a targeted edit without a human in the loop.
Two ideas make this practical, and they're the parts worth stealing even if you never run the server:
1. Content travels out-of-band → zero token cost
Coordination signals (what changed, who must react) are small and belong in the model's context. Document bodies are large and don't need to be *reasoned about* the moment they're written — they need to be stored and fetched on demand. So AgentNexus splits the two:
- **Control plane (MCP):** notifications, subscriptions, queries — a notification carries a version number and a unified diff, enough to decide *if* and *how* to react.
- **Data plane (plain HTTP POST /api/documents):** full document body, never passed as an MCP tool argument.
A document of any size costs **zero model tokens** on the write path. You pay tokens for *coordination*, not for *content*.
2. SDAOP — the service onboards the agent, not the other way around
AGENTS.md, CLAUDE.md, Cursor rules, Kiro steering — they all share one model: a human writes a static file, commits it, and the IDE loads it at startup. It goes stale, it drifts, and it's per-human busywork.
**Service-Driven Agent Onboarding Protocol (SDAOP)** flips this. The *service* generates and delivers client-specific onboarding at connection time. A new agent only needs the endpoint:
- Emits the right artifact for the client — .kiro/steering/, CLAUDE.md, AGENTS.md, or .cursor/rules/ — plus a push-tool script with the server URL baked in.
- Each artifact is **content-hash versioned**. Change a convention on the server, or move the server to a new URL, and the version bumps — connected workspaces detect the drift and re-onboard. No stale files, no manual notification.
- The service is the single source of truth; the client-side file is a derived artifact that regenerates as the service evolves.
Supported clients: kiro, claude, codex, cursor.
Quick Start
That's it — no separate DB migration or .env needed to get started. Everything
has sane defaults; copy .env.example to .env only when you want to change the
port, point at Postgres, or enable the Planner LLM.