Show HN: AgentNexus – coordinate LLM agents by service boundary, not role

AgentNexus, a new open-source framework, coordinates multiple LLM agents by service boundaries rather than roles, enabling automatic diff-aware notifications when documents change. The system uses a versioned document store with publish-subscribe mechanics, lifecycle stage tracking, and an MCP HTTP server to facilitate real-world software development workflows.

A service-boundary-aware coordination architecture for heterogeneous LLM code agents. "Service boundaries, not agent roles, are the appropriate primitive for coordinating LLM agents in real software development." Existing multi-agent frameworks ChatDev, MetaGPT organize agents around roles within a single simulated organization. AgentNexus takes a different approach: it coordinates agents at the service granularity, matching how real software systems are actually structured. Each service registers as a sub-project, publishes versioned Markdown documents requirements, design, API specs, config , and subscribes to documents from services it depends on. When a document changes, subscribers receive a diff-aware notification containing both the structured diff and the full latest content — enabling targeted, context-aware code modifications. Versioned document store — SHA-256 dedup, full version history, per-service 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 Lifecycle stage tracking — explicit design → development → testing → deployment → upgrade per service, with milestone snapshots on transitions Service-Driven Agent Onboarding SDAOP — generate instruction file auto-generates IDE steering files AGENTS.md, CLAUDE.md, Kiro steering, Cursor rules for any connecting agent MCP HTTP server — streamable-HTTP transport, multiple agents connect simultaneously Out-of-band write endpoint — POST /api/documents accepts full content via HTTP body zero LLM token cost FTS5 full-text search — search documents with BM25 ranking, phrase/prefix/boolean query support Planner AI layer — planner chat , planner plan , planner overview MCP tools + configurable LLM backend Web Dashboard — browser-based UI to explore spaces, projects, and documents with full-text search AI Chat — built-in chat panel powered by Planner LLM for conversational document Q&A and service planning 281 tests — unit + property-based Hypothesis ┌─────────────────────────────────────────────────────┐ │ Project Space │ │ │ │ ┌──────────────┐ subscribe ┌───────────────┐ │ │ │ search- │ ──────────────► │ search-admin- │ │ │ │ service │ │ frontend │ │ │ │ │ notification │ │ │ │ │ api/v5 ──────┼────────────────►│ │ │ │ └──────────────┘ └───────────────┘ │ │ │ │ AgentNexus MCP Server │ │ http://0.0.0.0:10086/mcp │ └─────────────────────────────────────────────────────┘ When a backend service updates its API document, the frontend agent is automatically notified with a structured diff — no human coordination needed: Backend Agent AgentNexus Frontend Agent │ │ │ │── push document ──────▶│ │ │ api, new version │── notification ─────────▶│ │ │ │── get my updates with context │ │◀─────────────────────────│ │ │── diff + full content ──▶│ │ │ │── apply targeted code changes │ │ │── ack update ────────────▶│ │ │ │ The diff payload looks like: { "doc id": "backend-service/api", "new version": 5, "diff": "@@ -42,6 +42,12 @@\n+ PUT /admin/docs/{doc id}\n+Update a document in-place...", "latest content": " API Spec\n\n..." } Install pip install -e ". dev " Initialize database python -m alembic upgrade head Start server default: http://0.0.0.0:10086/mcp python src/main.py { "mcpServers": { "doc-exchange": { "url": "http://localhost:10086/mcp" } } } Create a project space create space name="my-project" Register a service register project name="backend-api", type="development", project space id="<space id " Push a document push document project id="<project id ", doc id="<project id /api", content=" API Spec..." Subscribe frontend to backend's API docs add subscription subscriber project id="<frontend id ", project space id="<space id ", target doc id="<backend id /api" Check updates returns diff + full content get my updates with context project id="<frontend id " Once the server is running, open http://localhost:10086/ in your browser. Features: Browse — navigate spaces, sub-projects, and documents in a tree view Search — full-text search across all documents in a space AI Chat — ask questions about your project documents using natural language LLM configuration:AI Chat requires PLANNER LLM API KEY to be set. Set PLANNER LLM PROVIDER openai or anthropic and PLANNER LLM MODEL as needed. Leave the key unset to disable AI features while keeping all browse/search functionality. For zero-token document ingestion bypasses MCP tool-call LLM context , use the HTTP endpoint directly: 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..." }' This uses the same DocumentService.push pipeline as push document same validation, FTS index update, notifications but the document content never enters LLM context — making it practical for large documents. | Tool | Description | |---|---| create space | Create a Project Space | register project | Register a sub-project service | list projects | List all sub-projects in a space | list documents | List all documents in a sub-project | push document | Push a new document version full content | 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 IDE 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 | | Environment Variable | Default | Description | |---|---|---| DOC EXCHANGE DB URL | sqlite:///doc exchange.db | Database URL | DOC EXCHANGE DOCS ROOT | ./workspace | Workspace root docs live under {root}/{space id}/docs/ | DOC EXCHANGE HOST | 0.0.0.0 | Server bind host | DOC EXCHANGE PORT | 10086 | Server port | DOC EXCHANGE 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 | Each sub-project's IDE agent uses an onboarding file steering file, CLAUDE.md, AGENTS.md, etc. to auto-check for updates at session start. Generate one with: generate instruction file project name="my-service", project space id="<space id ", client type="kiro" Supported client type values: kiro , claude , codex , cursor . This is the Service-Driven Agent Onboarding Protocol SDAOP — the MCP service generates the onboarding document itself, so agents require zero manual configuration. See the v3 paper /dugubuyan/agent-nexus/blob/main/paper/agentnexus-v3.md for the formal protocol definition. python -m pytest tests/ -q The accompanying research papers are available in the paper/ /dugubuyan/agent-nexus/blob/main/paper directory: — v3 current : adds SDAOP paper/agentnexus-v3.md — v2 paper/agentnexus.md dugubuyan. AgentNexus: A Service-Boundary-Aware Coordination Architecture for Heterogeneous LLM Code Agents v3 .Zenodo, 2026. https://doi.org/10.5281/zenodo.20603176 MIT