npm version License: MIT Node.js

agent-pool-mcp

Multi-agent orchestration via CLI providers (Codex, Antigravity, OpenCode, and Claude Code) — parallel task delegation, sequential pipelines, cron scheduling, and cross-model peer review.

Compatible with Antigravity, Cursor, Windsurf, Claude Code, and any MCP-enabled coding agent.

Your primary IDE agent delegates background tasks to local CLI workers in parallel — each provider uses its own installed CLI authentication.

When the primary agent and Antigravity workers are different foundation models (e.g. Claude + Gemini), consult_peer gives you cross-model review — two models check each other's reasoning independently.

┌─────────────────────────────────┐
│  Primary IDE Agent              │  ← Claude, GPT, Gemini, etc.
│  (Antigravity / Cursor / ...)   │
└────────────┬────────────────────┘
             │ MCP (stdio)
┌────────────▼────────────────────┐
│  agent-pool-mcp                 │  ← This server
│  (task router + process mgmt)  │
└──┬─────────┬─────────┬─────────┘
   │         │         │
   ▼         ▼         ▼
  codex     agy       claude       ← CLI workers
  (task1)   (task2)   (review)       (same auth, parallel)

[!TIP] A Google AI Pro or Ultra subscription can power parallel Antigravity workers — no additional API keys required.

Task Delegation

Non-blocking task delegation to CLI workers. The primary agent fires off a task and continues working — polling for results when ready. Workers get full filesystem access (delegate_task) or read-only mode (delegate_task_readonly). Cancel anytime with cancel_task.

Codex tasks can pass model-specific reasoningEffort and serviceTier values. The same canonical fields are supported by resource-group profiles, scheduled tasks, and pipeline steps and are validated by the installed Codex CLI.

Pipelines — Sequential Task Chains

Multi-step workflows with automatic handoff between steps:

create_pipeline({
  name: "article-workflow",
  steps: [
    { name: "research", prompt: "Research the topic and write notes to research.md" },
    { name: "draft", prompt: "Read research.md and write article draft" },
    { name: "review", prompt: "Review the draft for accuracy and style" }
  ]
})
run_pipeline({ pipeline_id: "article-workflow" })

Steps support triggers: on_complete (chain after one step), on_complete_all (fan-in after several), and on_file (start when a file appears). Agents can bounce_back to a previous step with feedback if data is incomplete.

Cron Scheduler

Schedule agents on a cron expression — a detached daemon survives IDE/CLI restarts. Uses atomic file locks to prevent duplicate execution.

"0 9 * * MON-FRI"    — 9am weekdays
"*/30 * * * *"       — every 30 minutes
"0 */2 * * *"        — every 2 hours

Results are saved to .agent-portal/scheduled-results/ and retrievable via get_scheduled_results.

schedule_task({
  prompt: "Review open changes",
  cron: "0 9 * * MON-FRI",
  provider: "codex",
  model: "default",
  reasoningEffort: "high",
  serviceTier: "priority"
})

Team Memory Skill System

Skills are Markdown files with YAML frontmatter that extend agent behavior:

• Global — .agent-portal/skills/ inside the team-memory submodule.
• Workspace — .agent-portal/workspace/<project>/skills/ when the project context activates.
• Skills are loaded recursively and re-read by agent-pool on each run.
• Use create_skill, edit files directly, or manage shared skills through the Agent Portal UI.

Per-Task Policies

Restrict tool usage for specific tasks using YAML policies:

• "read-only" — disables all file-writing and destructive shell tools
• "safe-edit" — allows file modifications but blocks arbitrary shell execution
• Custom path — "/path/to/my-policy.yaml"

Cross-Model Peer Review

consult_peer sends architectural proposals to an Antigravity worker for structured review. The worker responds with a verdict: AGREE, SUGGEST_CHANGES, or DISAGREE. Supports iterative rounds until consensus.

Security

• Path Traversal Protection — all skill and policy operations are sanitized to prevent access outside designated directories
• Process Isolation — tasks run as detached processes; cancel_task and server shutdown kill entire process groups
• Credential Safety — uses your local CLI authentication; no keys are stored or transmitted

Quick Start

Prerequisites: Node.js >= 20 and at least one supported CLI installed and authenticated.

curl -fsSL https://antigravity.google/cli/install.sh | bash
agy       # First run: opens browser for OAuth

Claude Code tasks use provider: "claude" and require the claude CLI to be installed and authenticated with Claude Code's native auth. Agent Pool removes inherited Anthropic proxy/API env vars before spawning Claude Code so subscription/OAuth auth is not overridden by gateway settings.

OpenCode tasks use provider: "opencode". Install and authenticate OpenCode separately, then connect DeepSeek with /connect deepseek. DeepSeek V4 models use OpenCode's native model ids, for example deepseek/deepseek-v4-pro.

Add to your IDE's MCP configuration:

{
  "mcpServers": {
    "agent-pool": {
      "command": "npx",
      "args": ["-y", "agent-pool-mcp"]
    }
  }
}

Restart your IDE — agent-pool-mcp will be downloaded and started automatically.

npm install -g agent-pool-mcp

Verify

npx agent-pool-mcp --check

Runs diagnostics: checks Node.js, Antigravity CLI, authentication, and remote runner connectivity.

CLI

npx agent-pool-mcp --check      # Doctor mode: diagnose prerequisites
npx agent-pool-mcp --init       # Create template config (for SSH runners)
npx agent-pool-mcp --version    # Show version
npx agent-pool-mcp --help       # Full help

Shturman Benchmark

The experimental Phase-0 Shturman benchmark runs solo and chain-guided arms against OpenRouter with mechanical checks. It reads OPENROUTER_API_KEY from the environment and writes raw runs outside the repo by default:

npm run bench:shturman -- --config bench/examples/shturman-smoke.config.json

Remote Workers (SSH)

Run workers on remote servers via SSH — same interface, transparent stdio forwarding. Create agent-pool.config.json in your project root or ~/.config/agent-pool/config.json:

{
  "runners": [
    { "id": "local", "type": "local" },
    { "id": "gpu", "type": "ssh", "host": "gpu-server", "cwd": "/workspace/project" }
  ],
  "defaultRunner": "local"
}

Nested Orchestration

Install agent-pool inside Antigravity CLI to enable hierarchical delegation — workers can spawn their own workers.

See parallel-work guide and built-in orchestrator skill for patterns.

MCP Ecosystem

Best used as part of mcp-agent-portal — a unified MCP aggregator that combines all RND-PRO servers behind a single config entry:

{
  "mcpServers": {
    "agent-portal": {
      "command": "npx",
      "args": ["-y", "mcp-agent-portal"]
    }
  }
}

[!TIP] The Portal runs a singleton backend to prevent resource exhaustion when you open multiple IDE windows. It transparently spawns agent-pool-mcp and project-graph-mcp as child processes and aggregates their tools.

Also works standalone alongside project-graph-mcp — AST-based codebase analysis:

[!IMPORTANT] Each Antigravity CLI worker gets its own MCP server instance but shares pipeline state via filesystem — no coordination overhead.

Documentation

• ARCHITECTURE.md — Source code structure and process management details
• examples/parallel-work.md — Delegation patterns and best practices

Related Projects

• mcp-agent-portal — Unified MCP aggregator + web dashboard + AI agent runtime
• project-graph-mcp — AST-based codebase analysis for AI agents
• Symbiote.js — Isomorphic Reactive Web Components framework
• JSDA-Kit — SSG/SSR toolkit for modern web applications

License

MIT © RND-PRO.com

Made with ❤️ by the RND-PRO team