agent-nexus

AgentNexus

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.

Backend Agent              AgentNexus               Frontend Agent
  (Claude Code)                                        (Cursor)
      │                        │                          │
      │── POST /api/documents ▶│                          │
      │   (api spec, v5)       │── notification ─────────▶│
      │                        │                          │── get_my_updates_with_context()
      │                        │── diff + full content ──▶│
      │                        │                          │── applies targeted code change
      │                        │◀──────── ack_update() ───│

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:

generate_instruction_file(project_name="my-service", project_space_id="<space_id>", client_type="kiro")

• 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

# 1. Install
pip install -e .

# 2. Start the server — auto-creates the database on first run
#    (default: http://0.0.0.0:10086/mcp, dashboard at http://0.0.0.0:10086/)
python -m agent_nexus.main

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.

Run with Docker

docker build -t agent-nexus .
docker run -p 10086:10086 agent-nexus

To persist documents and the database across restarts, mount volumes:

docker run -p 10086:10086 \
  -v "$(pwd)/workspace:/app/workspace" \
  -v "$(pwd)/data:/app/data" \
  -e AGENT_NEXUS_DB_URL=sqlite:////app/data/agent_nexus.db \
  agent-nexus

Connect from Kiro / any MCP client:

{
  "mcpServers": {
    "agent-nexus": {
      "url": "http://localhost:10086/mcp"
    }
  }
}

First steps:

# Create a project space
create_space(name="my-project")

# Register two boundaries
register_project(name="backend-api", type="development", project_space_id="<space_id>")
register_project(name="frontend",    type="development", project_space_id="<space_id>")

# Push a document via HTTP POST (content stays out of LLM context)
# curl -X POST http://localhost:10086/api/documents -H 'Content-Type: application/json' \
#   -d '{"project_id":"<backend_id>","doc_id":"<backend_id>/api","content":"# API Spec..."}'

# Subscribe the frontend to the backend's API docs
add_subscription(subscriber_project_id="<frontend_id>", project_space_id="<space_id>", target_doc_id="<backend_id>/api")

# Frontend checks for updates (returns diff + full content)
get_my_updates_with_context(project_id="<frontend_id>")

Web Dashboard

Once the server is running, open http://localhost:10086/ in your browser to browse spaces, sub-projects, and documents, run full-text search, and use the built-in AI Chat for conversational document Q&A and service planning.

LLM configuration: AI Chat requires PLANNER_LLM_API_KEY. Set PLANNER_LLM_PROVIDER (openai or anthropic), PLANNER_LLM_MODEL, and optionally PLANNER_LLM_BASE_URL (Azure / Ollama / compatible APIs). Leave the key unset to disable AI features while keeping all browse/search functionality.

Key Features

• Versioned document store — SHA-256 dedup, full version history, per-boundary namespacing
• Publish-subscribe notifications — subscribe by exact doc ID or doc type
• Diff-aware updates — get_my_updates_with_context returns unified diff + full content in one call
• Control/data plane split — coordination over MCP, content over out-of-band HTTP (zero LLM token cost)
• SDAOP — services auto-generate versioned, client-specific onboarding files for any connecting agent
• Planner — a read-only, boundary-spanning observer (planner_chat, planner_plan, planner_overview) that answers cross-boundary questions no single agent can
• MCP HTTP server — streamable-HTTP transport, multiple agents connect simultaneously
• FTS5 full-text search — search_documents with BM25 ranking, phrase/prefix/boolean queries
• Web Dashboard + AI Chat — browser UI over spaces, projects, and documents
• 337 tests — unit + property-based (Hypothesis)

Out-of-Band Write Endpoint

The primary document write path. Content travels via HTTP body — never entering LLM context — so it's practical for documents of any size. Supports optional base_version for optimistic concurrency control (fast-forward check).

curl -X POST http://localhost:10086/api/documents \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "<project_id>",
    "doc_id": "<project_id>/requirement",
    "content": "# Requirements\n\nContent here..."
  }'

MCP Tools

| Tool | Description | |------|-------------| | create_space | Create a Project Space | | register_project | Register a sub-project (boundary) | | list_projects | List all sub-projects in a space | | list_documents | List all documents in a sub-project | | get_document | Retrieve a document (latest or specific version) | | get_my_updates_with_context | Get unread notifications with diff + full content | | ack_update | Mark a notification as read | | get_my_tasks | Get pending tasks for a project | | get_config | Get config document for a stage | | add_subscription | Add a subscription rule | | publish_draft | Confirm a draft document | | generate_instruction_file | Generate client-specific onboarding file (SDAOP) | | get_project_id_by_name | Look up project_id by name | | search_documents | Full-text search across documents in a space | | planner_chat | Conversational Q&A with LLM over project documents (streaming) | | planner_plan | Generate service-split proposal from a description | | planner_overview | Get a high-level overview of a project space |

Configuration

| Environment Variable | Default | Description | |---------------------|---------|-------------| | AGENT_NEXUS_DB_URL | sqlite:///agent_nexus.db | Database URL | | AGENT_NEXUS_DOCS_ROOT | ./workspace | Workspace root (docs live under {root}/{space_id}/docs/) | | AGENT_NEXUS_HOST | 0.0.0.0 | Server bind host | | AGENT_NEXUS_PORT | 10086 | Server port | | AGENT_NEXUS_PUBLIC_URL | (derived from host/port) | Outward-facing URL baked into onboarding files; changing it bumps the SDAOP version | | AGENT_NEXUS_DEFAULT_SPACE_ID | default | Default space ID for bootstrap imports | | PLANNER_LLM_PROVIDER | openai | LLM provider for Planner AI (openai \| anthropic) | | PLANNER_LLM_MODEL | (provider default) | LLM model name | | PLANNER_LLM_API_KEY | (none) | API key; leave empty to disable AI features | | PLANNER_LLM_BASE_URL | (none) | Custom API endpoint for OpenAI-compatible APIs (Azure, Ollama, proxies) |

Running Tests

python -m pytest tests/ -q

Paper

The accompanying research papers are in the paper/ directory:

• paper/agentnexus-v4.md — v4 (current): generalizes the coordination unit from service to ownership boundary, adds the control/data plane split and the Planner (中文版)
• paper/agentnexus-v3.md — v3: introduces SDAOP
• paper/agentnexus.md — v2

dugubuyan. AgentNexus: A Boundary-Aware Coordination Architecture for Heterogeneous LLM Code Agents (v4). Zenodo, 2026. https://doi.org/10.5281/zenodo.21257426

License

MIT