coding-agents-mcp

# coding-agents-mcp `coding-agents-mcp` is an Agent Hypervisor and universal Model Context Protocol (MCP) gateway designed to orchestrate autonomous CLI coding agents. It allows AI supervisors, IDEs (such as Cursor and Windsurf), and desktop assistants (like Claude Desktop and Google Antigravity) to manage subordinate coding agents including Anthropic's Claude Code, Google's Antigravity, OpenAI's Codex, and Cursor Agent. ## Core Philosophy The project emphasizes dependable simplicity and strict cross-platform parity across macOS, Linux, and Windows. Key architectural features include: * **Zero Daemon / Zero Root:** Operates as a pure, unprivileged Node.js stdio process. No Docker daemon, root privileges, or background services are required. * **Universal Sandboxing via Git Worktrees:** Executes agent runs in isolated, ephemeral Git worktrees on dedicated branches. This eliminates file churn and lock contention, allowing safe merge or discard operations. * **Cross-OS Consistency:** Rejects fragile OS-specific virtualization silos. All isolation, safety, and delegation features run identically across operating systems using standard Git and Node.js primitives. * **Process Safety:** Implements orphan-proof process reclamation using standard POSIX process groups on Unix and `taskkill` on Windows to ensure clean teardown. ## Key Capabilities 1. **Agent Hypervisor Paradigm:** Provides a goal-oriented substrate where supervising models dictate intent, invariants, and acceptance criteria, while subordinate agents execute micro-decisions autonomously. 2. **Stateful Sessions:** Automatically preserves multi-turn conversation memory across calls with zero token wire overhead. 3. **Inter-Agent Handoffs:** Transfers tasks between different models using structured packets (objectives, file manifests, git diffs) rather than raw transcripts, preventing context window explosion. 4. **Multi-Agent Orchestration:** Supports built-in declarative topologies such as `architect_builder`, `peer_review`, and custom DAGs with automatic rollback and diff verification. 5. **Ephemeral Sandboxing:** Uses detached worktrees to isolate agent runs, ensuring the main workspace remains clean until changes are explicitly merged. ## Supported Agents | Agent | CLI Binary | Status | | :--- | :--- | :--- | | Anthropic Claude Code | `claude` | Supported | | Google Antigravity | `agy` | Supported | | OpenAI Codex CLI | `codex` | Adapter Ready | | Cursor Agent | `cursor` | Adapter Ready | ## Toolset Reference The gateway exposes several tools for delegation, inspection, and orchestration: * **Core Delegation:** `delegate_task` for autonomous pair programming, `delegate_ask` for read-only queries, and `delegate_diff` for workspace inspection. * **Session Management:** `delegate_sessions` and `delegate_reset` to manage conversation state. * **Worktree Management:** `delegate_worktree` to list, inspect, merge, or discard isolated sandboxes. * **Orchestration:** `delegate_pipeline` for multi-agent workflows and `delegate_handoff` for structured task transfers. * **Messaging:** `agent_mailbox` for asynchronous coordination between agents. ## Quick Start Run directly via `npx`: ```bash npx -y coding-agents-mcp ``` ### Configuration Examples **Claude Desktop (`claude_desktop_config.json`):** ```json { "mcpServers": { "coding-agents": { "command": "npx", "args": ["-y", "coding-agents-mcp"] } } } ``` **Cursor (`~/.cursor/mcp.json`):** ```json { "mcpServers": { "coding-agents": { "command": "npx", "args": ["-y", "coding-agents-mcp"] } } } ``` **Google Antigravity Sidecar:** ```json { "mcpServers": { "coding-agents": { "command": "npx", "args": ["-y", "coding-agents-mcp", "--compat=agy"] } } } ``` ## Development To build and test locally: ```bash git clone https://github.com/funkyfunc/coding-agents-mcp.git cd coding-agents-mcp npm install npm run build npm test ``` The project is licensed under MIT.