{"id":"094d1b4d-ffbe-41b4-a637-106ccb03e30d","slug":"devjoaocastro-agent-mesh","kind":"mcp","name":"agent-mesh","summary":"Decentralized coordination protocol for AI agents across IDEs and LLMs","owner":"devjoaocastro","repoUrl":"https://github.com/devjoaocastro/agent-mesh","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-03-08T01:39:04.000Z","addedAt":"2026-10-21T08:30:04.374Z","logoUrl":"https://avatars.githubusercontent.com/u/169039592?u=a06348bcfa171ebbc8a2a2f4d0dbc98c1fbf29b5&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","files-documents"],"tags":["agents","ai","claude-code","codex","coordination","cursor","developer-tools","filesystem"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T18:22:15.606Z","sample":false,"url":"https://conduits.dev/tools/devjoaocastro-agent-mesh","language":"JavaScript","transports":["stdio"],"install":{"npm":"agent-mesh"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"\n\n# AgentMesh\n\n### Your AI agents can now talk to each other.\n\n**Any LLM. Any IDE. Zero infrastructure.**\n\n[](https://www.npmjs.com/package/agent-mesh)\n[](https://opensource.org/licenses/MIT)\n[]()\n[]()\n[]()\n[]()\n[](https://github.com/CodeAheadDev/agent-mesh/stargazers)\n[](https://github.com/CodeAheadDev/agent-mesh/network/members)\n\n
\n\n*Claude Code in one terminal. Codex in another. Cursor in a third.*\n*They're all working on your project — but they can't coordinate.*\n*Until now.*\n\n
\n\n```\n$ am route \"Build a todo app. @codex write the API. @cursor build the UI. @claude review both.\"\n\n ✓ task-f465 → @codex: \"Write the API\"\n ✓ task-2273 → @cursor: \"Build the UI\"\n ✓ task-19e6 → @claude: \"Review both\"\n\n 3 tasks created. Instructions delivered. Agents coordinating.\n```\n\n
\n\n---\n\n## The Problem\n\nYou're running 3 AI agents right now. Claude Code is refactoring the backend. Codex is writing tests. Cursor is fixing the frontend.\n\nThey all have access to the same codebase, but:\n\n- **They can't talk to each other.** Claude doesn't know Codex just changed the API schema.\n- **They overwrite each other's work.** Cursor edits a file that Claude is also editing.\n- **They make contradictory decisions.** One picks PostgreSQL, another writes SQLite queries.\n- **They duplicate effort.** Two agents independently write the same utility function.\n\nEvery multi-agent tool today either locks you into **one LLM** (Claude Teams, Codex fan-out) or requires a **central server** (A2A, ACP, BeadHub). Nothing coordinates across Claude + Codex + Cursor + Windsurf + local LLMs with zero setup.\n\n## The Solution\n\nAgentMesh is a **filesystem-based coordination protocol**. Drop `.agent-mesh/` in any project and every AI agent — regardless of provider or IDE — can read tasks, send messages, claim work, and coordinate.\n\n**No API server. No SDK per IDE. No vendor lock-in. Just JSON files.**\n\n> Every AI coding agent can read and write files. That's the universal interface. AgentMesh turns the filesystem into a coordination layer.\n\n---\n\n## Quick Start\n\n```bash\nnpm install -g agent-mesh\n\ncd my-project\nam init\n\n# Register agents (run in each IDE/terminal)\nam register claude-code architect\nam register codex builder\nam register cursor specialist\n\n# Route work with @mentions\nam route \"Build auth. @codex write the API. @cursor build the login UI. @claude review security.\"\n```\n\nEach agent gets a task file with full context about what others are doing. They coordinate through the shared filesystem.\n\n### Zero Manual Setup\n\nWhen you run `am register`, AgentMesh **automatically injects instructions** into the agent's native config file. No need to manually tell each agent about the mesh:\n\n| Agent | Auto-created file | How agent discovers it |\n|-------|------------------|----------------------|\n| Claude Code | `CLAUDE.md` | Read on every conversation start |\n| Codex CLI | `.codex/instructions.md` | Read on every task |\n| Cursor | `.cursor/rules/agent-mesh.mdc` | Loaded as always-on rule |\n| Windsurf | `.windsurfrules` | Read on startup |\n| Copilot | `.github/copilot-instructions.md` | Read on startup |\n| Cline | `.clinerules` | Read on startup |\n| Aider | `.aider.conf.yml` | `read:` directive for PROTOCOL.md |\n| Other | `.agent-mesh/AGENT_INSTRUCTIONS.md` | Point your agent here |\n\nFor Claude Code and Cursor, `am register` also auto-installs the MCP server — giving them native mesh tools in their chat interface.\n\n---\n\n## Why It Works: The Protocol\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│ Your Project │\n│ │\n│ ┌──────────┐ ┌────────────────────┐ ┌──────────┐ │\n│ │ Claude │ │ .agent-mesh/ │ │ Codex │ │\n│ │ Code │◄───►│ │◄───►│ CLI │ │\n│ │ │ │ agents/ │ │ │ │\n│ └──────────┘ │ tasks/ │ └──────────┘ │\n│ │ messages/ │ │\n│ ┌──────────┐ │ context/ │ ┌──────────┐ │\n│ │ Cursor │◄───►│ artifacts/ │◄───►│ Local │ │\n│ │ IDE │ │ PROTOCOL.md │ │ LLM │ │\n│ └──────────┘ └────────────────────┘ └──────────┘ │\n│ ▲ │\n│ ┌──────────────┐ │\n│ │ Daemon │ (optional) │\n│ │ WebSocket │ real-time events │\n│ └──────────────┘ │\n└──────────────────────────────────────────────────────────────┘\n```\n\n| Directory | Purpose |\n|-----------|---------|\n| `agents/` | Agent registry — who's in the mesh, their role, capabilities |\n| `tasks/` | Shared task board — create, claim, complete tasks |\n| `messages/` | Inter-agent messages — questions, answers, handoffs, alerts |\n| `context/` | Shared knowledge — decisions log, shared variables, file locks |\n| `artifacts/` | Shared outputs — routing plans, code snippets, research |\n| `PROTOCOL.md` | Self-describing spec — any new agent reads this to participate |\n\n### Why Files?\n\nEvery AI coding agent can read and write files. That's the one thing Claude Code, Codex, Cursor, Copilot, Windsurf, Devin, Aider, Cline, and every local LLM have in common.\n\n- **Zero integration cost** — no SDK, no API, no plugin per IDE\n- **Works offline** — no server, no network dependency\n- **Git-friendly** — commit and share coordination state\n- **Inspectable** — `cat` any JSON file to see what's happening\n- **Crash-resilient** — agent crashes, state persists on disk\n\n---\n\n## Features\n\n### @Mention Routing\n\nRoute work to agents using natural `@mentions`:\n\n```bash\nam route \"Build e-commerce. @codex backend API. @cursor React storefront. @claude database design.\"\nam route \"@cursor fix the broken CSS on mobile --priority critical\"\nam route plan \"Refactor payments. @codex Stripe. @cursor checkout UI.\" # dry run\n```\n\nEach agent receives a task + message with full context about what others are doing.\n\n### Shared Task Board\n\n```bash\nam task create \"Build user authentication\"\nam task list\nam task list --status open\nam task claim task-abc123 agent-xyz\nam task update task-abc123 \"Login endpoint done\"\nam task complete task-abc123 \"All endpoints tested\"\n```\n\n### Inter-Agent Messaging\n\n```bash\nam msg send codex \"API schema is ready\"\nam msg send cursor \"Don't touch header.tsx, I'm refactoring it\" --type alert\nam msg broadcast \"Switching to TypeScript strict mode\"\nam msg read --unread\nam msg decide \"Use PostgreSQL\" --context \"Need JSONB support\"\n```\n\n### Token-Aware Context\n\nAgents have limited context windows. AgentMesh compresses coordination state to fit any budget:\n\n```bash\nam context summary # full context (~400 tokens)\nam context brief --tokens 500 # compressed to fit budget\nam context tokens # cost breakdown per model\n```\n\n**Measured token savings** (5 agents, 8 tasks, 6 messages, 3 decisions):\n\n| Mode | Tokens | Savings |\n|------|--------|---------|\n| Raw JSON (no AgentMesh) | ~1,700 | — |\n| Full summary | ~400 | **76% reduction** |\n| Budgeted brief | ~220 | **87% reduction** |\n\nContext window usage with 8 agents and 15 active tasks:\n\n| Model | Usage |\n|-------|-------|\n| Claude 4 (200k) | 0.23% |\n| GPT-4o (128k) | 0.36% |\n| Codex (192k) | 0.24% |\n| Gemini 2.5 (1M) | 0.05% |\n\n### File Conflict Detection\n\n```bash\nam watch start # monitor file changes\nam watch status # see active locks\nam watch report # hotspot detection\n```\n\n### MCP Integration\n\nNative tool support in Claude Code and Cursor via [Model Context Protocol](https://modelcontextprotocol.io):\n\n```bash\nam mcp install # auto-configures\n```\n\n8 tools available: `mesh_status`, `mesh_route`, `mesh_send`, `mesh_read`, `mesh_tasks`, `mesh_init`, `mesh_register`, `mesh_decide`\n\n### Real-Time Daemon (Optional)\n\n```bash\nam daemon # WebSocket on ws://localhost:4200\n```\n\nFile watcher + WebSocket server for instant notifications when tasks change.\n\n---\n\n## Supported Agents (19)\n\nAgentMesh auto-detects capabilities and environment for every major AI coding agent:\n\n| Agent | Environment | Auto-detected Capabilities |\n|-------|-------------|---------------------------|\n| **Claude Code** | Terminal/CLI | full-stack, architecture, code-review, debugging |\n| **OpenAI Codex** | Terminal/CLI | code-generation, refactoring, tests, fan-out |\n| **Cursor** | Cursor IDE | frontend, ui, rapid-iteration, multi-agent |\n| **Windsurf** | Windsurf IDE | full-stack, multi-file, autonomous |\n| **GitHub Copilot** | VS Code/JetBrains | autocomplete, snippets, pr-review |\n| **Devin** | CLI/Cloud | autonomous, full-stack, deployment |\n| **Aider** | Terminal/CLI | git, code-editing, pair-programming |\n| **Cline** | VS Code | full-stack, autonomous, browser, terminal |\n| **Continue** | VS Code | autocomplete, chat, multi-model |\n| **Bolt** | Browser | frontend, react, rapid-prototype |\n| **Lovable** | Browser | frontend, design-to-code |\n| **Replit** | Browser/IDE | full-stack, deployment, collaboration |\n| **v0** | Browser | frontend, ui, react, design-to-code |\n| **Gemini** | CLI/Cloud | full-stack, code-generation, multi-modal |\n| **Qwen** | CLI | code-generation, multilingual |\n| **Ollama** | Local | local, privacy, code-generation |\n| **LM Studio** | Local | local, privacy, fine-tuning |\n| **Tabby** | Self-hosted | autocomplete, self-hosted, code-completion |\n| **Sourcegraph Cody** | VS Code/Web | code-search, refactoring, codebase-wide |\n\nRegister with auto-detection:\n```bash\nam register claude-code architect # auto-detects capabilities\nam register my-custom-bot builder # defaults to \"general\"\n```\n\n---\n\n## For AI Agents: How to Participate\n\n**No CLI needed.** Any agent that can read/write files just follows `.agent-mesh/PROTOCOL.md`:\n\n**1. Register** — Write JSON to `.agent-mesh/agents/`:\n```json\n{ \"id\": \"agent-xxx\", \"name\": \"my-agent\", \"role\": \"builder\", \"status\": \"active\" }\n```\n\n**2. Check tasks** — Read `.agent-mesh/tasks/`, look for `\"status\": \"open\"`.\n\n**3. Communicate** — Write JSON to `.agent-mesh/messages/`.\n\nThe protocol is self-describing. Point any agent at `PROTOCOL.md` and it knows what to do.\n\n---\n\n## Programmatic API\n\n```javascript\nimport { AgentMesh } from 'agent-mesh';\n\nconst mesh = new AgentMesh();\n\nconst agent = await mesh.register('my-bot', 'builder');\nconst task = mesh.createTask('Build login page', { priority: 'high' });\nmesh.sendMessage('codex-id', 'Schema updated, regenerate types');\nmesh.broadcast('Deploying to staging');\nmesh.logDecision('Use PostgreSQL', 'Need JSONB support');\n```\n\n---\n\n## Benchmarks\n\n### Coordination: With vs Without AgentMesh\n\nSimulated 5 agents working on 12 tasks across 18 project files, averaged over 5 runs:\n\n| Metric | Without AgentMesh | With AgentMesh |\n|--------|:-:|:-:|\n| File conflicts | 9 | **0** |\n| Silent overwrites | 9 | **0** |\n| Duplicate work | 8 | **0** |\n| Dependency violations | 4 | **0** |\n| Decision conflicts | 2 | **0** |\n| Work efficiency | 75% | **100%** |\n\n### Cross-IDE Protocol Proof\n\nTested 6 agents from different IDEs writing to the same `.agent-mesh/`:\n\n| Metric | Result |\n|--------|--------|\n| Agents registered (6 IDEs) | 6/6 |\n| Tasks visible across all | 6/6 |\n| Messages delivered cross-IDE | 6/6 |\n| Protocol overhead | **4.2 KB** |\n\n### Test Coverage\n\n**105 automated tests** across 5 suites:\n\n| Suite | Tests | What It Proves |\n|-------|-------|----------------|\n| Full flow | 26 | CLI commands, registration, routing, messaging |\n| Security | 21 | Path traversal, injection, atomic writes, validation |\n| Real-world simulation | 39 | 8 agents, 6 IDEs, e-commerce project coordination |\n| Token savings + proof | 8 | Token reduction, conflict elimination, dependency order |\n| Auto-config injection | 11 | Config files created for 8 agent types, append/update/no-overwrite |\n\n---\n\n## vs. Alternatives\n\n| Feature | AgentMesh | A2A (Google) | MCP | ACP (IBM) | Claude Teams | Codex Fan-out |\n|---------|-----------|-------------|-----|-----------|-------------|---------------|\n| Cross-LLM | **Yes** | Yes | No | Yes | No | No |\n| Cross-IDE | **Yes** | N/A | Partial | N/A | No | No |\n| Zero infrastructure | **Yes** | No (HTTP) | No (server) | No (server) | No | No |\n| @mention routing | **Yes** | No | No | No | No | No |\n| Token awareness | **Yes** | No | No | No | No | No |\n| File conflict detection | **Yes** | No | No | No | No | No |\n| Works offline | **Yes** | No | No | No | No | No |\n| Self-describing protocol | **Yes** | Yes | Partial | Yes | No | No |\n\n**Key differentiator:** AgentMesh is the only tool that bridges agents **across different IDEs and LLMs**. Claude Teams only coordinates Claude agents. Codex fan-out only orchestrates Codex workers. Cursor multi-agent only works within Cursor. AgentMesh connects all of them through the one thing they all share: **the filesystem**.\n\n---\n\n## Configuration\n\n```json\n// .agent-mesh/mesh.json\n{\n \"version\": \"0.1.0\",\n \"project\": \"my-project\",\n \"settings\": {\n \"daemon_port\": 4200,\n \"heartbeat_interval\": 30000,\n \"task_timeout\": 300000,\n \"max_messages_per_agent\": 100\n }\n}\n```\n\n---\n\n## Security\n\n- **Input validation** — all IDs and names validated against strict regex\n- **Path traversal protection** — `safePath()` prevents directory escape\n- **Atomic writes** — temp file + rename prevents corruption\n- **Localhost-only daemon** — WebSocket binds to `127.0.0.1`\n- **No command injection** — `execFileSync` instead of `execSync`\n\n---\n\n## Contributing\n\n```bash\ngit clone https://github.com/CodeAheadDev/agent-mesh.git\ncd agent-mesh\nnpm install\nnode --test tests/\n```\n\n---\n\n## Roadmap\n\n- [ ] Agent hooks — custom scripts on mesh events\n- [ ] Remote mesh — sync across machines via git\n- [ ] Web dashboard — browser monitoring UI\n- [ ] A2A bridge — Google Agent2Agent protocol interop\n- [ ] Voting system — consensus-based decisions\n- [ ] Auto-summarization — compress old context\n\n---\n\n## Philosophy\n\n1. **Files are the universal interface.** Every agent can read/write files.\n2. **Protocol over platform.** The spec matters more than the tool.\n3. **Zero infrastructure.** No server = more adoption.\n4. **Inspectable by default.** `cat` any JSON file.\n5. **Agents are peers.** No hierarchy.\n\n---\n\n\n\n**Built by [CodeAhead](https://codeahead.dev)**\n\n[Report Bug](https://github.com/CodeAheadDev/agent-mesh/issues) · [Request Feature](https://github.com/CodeAheadDev/agent-mesh/issues)\n\n
\n"}