n2ns Nexus 🚀

n2ns Nexus is a local coordination hub for multi-AI assistant collaboration. A standalone daemon process owns all data and business logic; stateless MCP adapters connect to it from any IDE, on any machine.

Works with: Claude Code · Claude Desktop · VS Code · Cursor · Windsurf · Zed · JetBrains · Theia

📖 Documentation: CHANGELOG | Architecture | AI Assistant Guide | 中文文档

🏗️ Architecture

┌──────────────────────────────────────┐
│         n2n-nexus daemon             │
│  Standalone HTTP server · Always on  │
│  Owns all data, tools & business logic│
└──────────────┬───────────────────────┘
               │ HTTP (NEXUS_ENDPOINT)
       ┌───────┼───────┐
       ▼       ▼       ▼
    MCP-A   MCP-B   MCP-C
   (Win)   (WSL)   (VM)
  Stateless proxy per IDE

• Daemon is the single source of truth — start it once, keep it running.
• MCP adapters are stateless — spawned by each IDE via npx, they fetch the tool list from the daemon and forward every tool call to it.
• Cross-environment: set NEXUS_ENDPOINT to point any IDE at the same daemon, even across Windows/WSL/VM boundaries.

🚀 Quick Start

1. Start the daemon (once, keep it running)

npx n2n-nexus daemon --port 5688

2. Configure each IDE's MCP client

{
  "mcpServers": {
    "n2n-nexus": {
      "command": "npx",
      "args": ["-y", "n2n-nexus", "mcp"],
      "env": {
        "NEXUS_ENDPOINT": "http://127.0.0.1:5688"
      }
    }
  }
}

The MCP adapter starts with an empty tool list and automatically loads tools from the daemon once it's reachable. You can start the IDE before the daemon — tools will appear when the daemon comes up.

Cross-environment endpoint examples

🛠️ Toolset

A. Session & Context

• register_session_context — Declare the active project ID ([prefix]_[name] format).

B. Project Asset Management

• sync_project_assets [ASYNC] — Submit full Project Manifest + internal docs. Returns taskId.
• update_project — Partial manifest patch (e.g. update endpoints only).
• rename_project [ASYNC] — Rename project ID with cascading relation updates. Returns taskId.
• upload_project_asset — Upload binary/text file (base64) to project vault.
• search_projects — Search registry by name or description.
• get_global_topology — Default: project list + stats. With projectId: detailed dependency subgraph.

C. Messaging & Global Collaboration

• send_message — Post to active meeting or global chat. Categories: MEETING_START PROPOSAL DECISION UPDATE CHAT.
• read_messages [Incremental] — Returns only unread messages per instance; cursor auto-advances.
• update_global_strategy — Overwrite the master strategy document.
• sync_global_doc — Create or update a cross-project shared document.

D. Meeting Management

• start_meeting — Open a new meeting session.
• end_meeting — Close and lock a meeting (with optional summary).
• archive_meeting — Move closed meeting to cold storage.
• reopen_meeting — Reactivate a closed or archived meeting.

E. Task Management (Async)

• create_task — Create a background task. Returns taskId.
• get_task — Poll status, progress (0.0–1.0), and result.
• list_tasks — List tasks with optional status filter.
• cancel_task — Cancel a pending or running task.

F. Maintenance

• host_maintenance — Prune (oldest N) or clear all system logs.
• host_delete_project [ASYNC] — Permanently delete a project and all its assets.

💾 Data Storage (Zero-Config)

Default storage root:

Override with --root <path> or NEXUS_ROOT env var.

Storage layout:

~/.n2n-nexus/
├── global/
│   ├── blueprint.md        # Master strategy
│   ├── docs_index.json     # Global docs index
│   └── docs/               # Shared markdown docs
├── projects/
│   └── {project-id}/
│       ├── manifest.json
│       ├── internal_blueprint.md
│       └── assets/
├── registry.json           # Project index
└── nexus.db                # SQLite (meetings, tasks, cursors)

🏷️ Project ID Conventions

All project IDs must follow [prefix]_[name] format:

🔧 CLI Reference

# Start daemon
n2n-nexus daemon [--port 5688] [--root ~/.n2n-nexus]

# Start MCP adapter (IDE calls this automatically via npx)
NEXUS_ENDPOINT=http://127.0.0.1:5688 n2n-nexus mcp

Environment variables

📋 Real-World Example: Multi-AI Collaboration

The following files demonstrate a real session where 4 AI agents (Claude, ChatGPT, Gemini, Augment) collaborated to design an authentication system and Edge-Sync Protocol:

Local Development

git clone https://github.com/n2ns/n2n-nexus.git
cd n2n-nexus
npm install
npm run build

# Run daemon
node build/index.js daemon --root /tmp/nexus-test --port 5688

# Run MCP (separate terminal)
NEXUS_ENDPOINT=http://127.0.0.1:5688 node build/index.js mcp

⭐ Support This Project

About N2NS Lab

Built by N2NS Lab — Next-to-Native Systems Lab, Datafrog's open-source lab for AI-native developer tools.