polyagent-mcp

MCP server that lets any agent or MCP host delegate to headless Codex, Grok, Claude Code, and
OpenCode CLIs, with Cursor available as an opt-in fallback. Use the fleet for implementation, planning,
and project exploration without burning the caller's context on raw worker output.

Worker tools take optional model and effort overrides, return a session_id, and support
follow_up. Three named difficulty levels select distinct default models on the Codex and Claude
subscriptions; delegate also accepts an explicit engine, including pay-per-token OpenCode.

Tools

The server exposes twelve tools:

Worker tools accept cwd, model, and effort where applicable. delegate requires a level
("low", "middle", or "high"); fast_delegate has none and picks the fastest healthy engine. Explicit model/effort
values override the selected tier.

When an engine runs out of quota

A call that fails because the engine's plan quota is exhausted does not silently retry on
another engine — spending the next subscription is your decision. The call fails with an actionable
error naming the engines still available (installed, enabled, and capable of what that tool needs)
and how to switch: engine:"<x>" on the four auxiliary tools and delegate, or the lowest
still-usable level:"<name>" when a tier engine remains. Tools that pick the engine themselves (fast_delegate, fan_out) and follow_up
(pinned to the resumed session's engine) report the quota without suggesting a parameter, and
generate_image reports it against the two engines that have an image tool at all (codex, grok). A transient rate limit is reported separately and asks you to wait, since switching
engines would not help. Anything the classifier does not recognize — an expired login, for one —
propagates as the raw CLI failure instead of being guessed at.

Requirements

• Node ≥ 18
• bubblewrap (bwrap) installed — required, not recommended: the sandbox is mandatory and the
  server refuses to start without it (sudo apt install bubblewrap). Only POLYAGENT_SANDBOX=off
  waives it, as an explicit operator choice.
• Codex installed and authenticated for low/middle; Claude Code for high. Read tools use the
  fast candidate cascade. Grok and OpenCode are optional fallbacks or explicit engine overrides.
• Optional Cursor fallback: install cursor-agent and set POLYAGENT_ENABLE_CURSOR=1.

Install

Installing via an AI agent? Point it at INSTALL.md — an agent-facing,
copy-paste guide that detects the host and registers the bridge in Claude Code, Cursor,
Codex, Grok, or any generic MCP host.

git clone https://github.com/JaimeJunr/polyagent-mcp.git
cd polyagent-mcp
npm install
npm run build

Register in an MCP host

Claude Code:

claude mcp add polyagent -s user -- node /abs/path/to/polyagent-mcp/dist/index.js

Any host — add to its mcp.json:

{
  "mcpServers": {
    "polyagent": {
      "command": "node",
      "args": ["/abs/path/to/polyagent-mcp/dist/index.js"]
    }
  }
}

Permissions (Claude Code): claude mcp add registers the server but does not grant
tool permission — without an allowlist every bridge call prompts for approval. After
registering, add either "mcp__polyagent__*" (full; also auto-approves mutating tools
delegate/fast_delegate/run_filtered/follow_up) or a read-only subset
(explore/read_slice/web_lookup/bridge_stats) under
permissions.allow in settings.json. Full options and trade-offs:
INSTALL.md §3. Cursor/Codex/other hosts
have their own approval settings — consult the host.

Configuration (env)

The three Jev flags are on by default (without an OpenRouter key each one falls back to the plain path) and pass truncated worker output or task text through the credential scrubber before sending it to OpenRouter.
They use the same OPENROUTER_API_KEY or OpenCode auth-file key as decide.

Breaking change: env var rename

Every CURSOR_BRIDGE_* variable was renamed to POLYAGENT_* (same suffix), and CURSOR_BIN
became POLYAGENT_CURSOR_BIN. This is a clean cut: the old names are no longer read at all —
setting one has zero effect (no fallback, no warning). Update your host config (mcp.json /
settings.json "env" blocks) and any shell profile before upgrading.

"cursor" survives only where it names the actual Cursor engine (POLYAGENT_CURSOR_BIN,
POLYAGENT_ENABLE_CURSOR).

Security: delegate, fast_delegate, and run_filtered have full access and auto-approve
their work. explore, read_slice, and web_lookup use Codex's read-only sandbox. Named agents
are resolved on the host, reject path traversal, and are injected without mounting agent
directories.

Make the agent actually use it

Managed CLAUDE.md block. Run npm run install-claude-md -- --dry-run to preview, then
npm run install-claude-md (or npx -p polyagent-mcp polyagent-mcp-install-claude-md). It appends a
routing block to ~/.claude/CLAUDE.md between <!-- polyagent-mcp:begin … --> and
<!-- polyagent-mcp:end -->, replaces an old hand-written <polyagent_preference> section, and saves
CLAUDE.md.polyagent.bak. From then on the server refreshes the block on each start (only when the
markers exist). Set POLYAGENT_CLAUDE_MD=off to stop that, or delete both markers.

Managed polyagent skill. Run npm run install-skill -- --dry-run to preview, then
npm run install-skill (or npx -p polyagent-mcp polyagent-mcp-install-skill). It writes
polyagent/SKILL.md into ~/.claude/skills (Claude Code) and ~/.agents/skills (Codex, OpenCode and
other AGENTS-aware clients); override the roots with POLYAGENT_SKILL_ROOTS (:-separated). The
CLAUDE.md block stays short because it loads every session; the skill loads only when the task matches
and carries the how-to: tool choice, a stand-alone worker prompt, levels, deny, handing over agents and
skills, follow_up and rate. Like ai-memory's skills, the file carries an ownership marker
(<!-- polyagent-mcp-managed: routing-skill … -->): a same-name skill without it is never overwritten,
and the server refreshes marked copies on each start. Set POLYAGENT_SKILL=off to stop that.

Registering the tools is not enough. Two structural forces push the agent back to
native tools: (1) the host rule "prefer the dedicated file/search tools", and (2) MCP
tools used to be deferred — the agent had to run a tool-search to load their schemas,
so always-loaded Read/Grep/WebSearch won by default. The server now publishes
startup instructions (routing boundary) and marks the five core tools, fast_delegate,
fan_out, and rate with
_meta: { "anthropic/alwaysLoad": true } (Claude Code ≥2.1.121) so their schemas load
eagerly. Both fast_delegate and fan_out joined them after they were deferred and never got
called — the same adoption bug. The remaining secondary tools (generate_image, follow_up,
bridge_stats, decide) stay deferred. Four fixes, strongest first:

1. Call-time hook (recommended). A PreToolUse hook that steers the agent toward
the bridge at the moment it reaches for a native tool — text in a config file loses under
pressure, a call-time reminder does not. This repo ships one at
hooks/prefer-polyagent.mjs: it runs on node
(already required) and only fires where it pays. Default mode is redirect
(POLYAGENT_HOOK_MODE=redirect): para WebSearch/WebFetch, Read grande e Bash de busca de código,
retorna permissionDecision: "deny" uma vez e indica a ferramenta do bridge. Os demais casos
emitem nudges sem bloqueio. Configure no settings.json do host Claude Code:

Breaking change (US-007): The hook file was renamed from
hooks/prefer-cursor-bridge.mjs to hooks/prefer-polyagent.mjs. Update any host
settings.json entry that points to the old path.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          { "type": "command", "command": "node /abs/path/to/polyagent-mcp/hooks/prefer-polyagent.mjs", "timeout": 5 }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Read|Grep|Glob|WebSearch|WebFetch|Bash|Edit|Write|MultiEdit|Agent|Task",
        "hooks": [
          { "type": "command", "command": "node /abs/path/to/polyagent-mcp/hooks/prefer-polyagent.mjs", "timeout": 5 }
        ]
      }
    ]
  }
}

UserPromptSubmit runs on every submitted prompt. That event has no matcher field; the hook's
promptRouteContext() detects routing cues and stays silent when none match. This path is
intentionally not deduplicated: each prompt is judged on its own.

For PreToolUse, each nudge/redirect fires at most once per session (deduplicated in a tmp
file keyed by session_id), because a repeated fire is worse than none: the agent learns
to ignore it and every fire costs tokens. Dedup keys are saved before emitting so
redirect is one-shot and fail-open (a second identical call is allowed through).

• Read whole-file (no offset/limit) over POLYAGENT_HOOK_MIN_LINES lines →
  redirect (default) or nudge toward read_slice (once per file). Partial reads are left alone.
• WebSearch/WebFetch → redirect (default) or nudge toward web_lookup (once).
• Grep/Glob → emits the one-time preload reminder to run the ToolSearch for any
  still-deferred bridge tools (nudge only — never redirected). The dedup collapses them to a
  single fire.
• Bash com busca de código no primeiro segmento da pipeline (grep/rg/egrep/fgrep/
  ag/ack/find ou git grep, após rtk ou atribuições de ambiente) → redirect uma vez para
  explore/read_slice; em nudge, apenas additionalContext. Cada && inicia nova pipeline.
  npm test | grep FAIL e ps aux | grep x não disparam. Comandos que também gravam artefatos
  não são redirecionados. O nudge existente de git commit/push, git worktree add,
  gh pr create, gh issue create, bkt pr create tem prioridade.
• Agent/Task → nudge uma vez por sessão para delegate/fast_delegate com
  agent: "<subagent name>". A ferramenta nativa fica para etapas que exigem MCP servers ou
  browser. Helpers claude-code-guide e
  statusline-setup são isentos.
• Skill não é tratada pelo hook desde 2026-10-25: o deny fazia o host empurrar até skills
  básicas para um worker, embora usar a tool nativa seja válido. delegate ainda aceita
  agent: { skill: "plugin:name" } quando o chamador escolhe esse handoff; o hook não o sugere.
• Edit/Write/MultiEdit → once per session, reminds that a self-contained task
  (feature, bugfix, mechanical multi-file change, build fix) can go whole to delegate(prompt, level)
  — the selected worker edits with full access — instead of the orchestrator implementing
  it on expensive tokens. It never blocks the edit (nudge only); the once-per-session dedup means
  the orchestrator still edits inline freely (the nudge repositions execution, it doesn't police every edit).
• The first qualifying fire of the session (whichever tool triggers it) also carries
  that preload reminder, so secondary schemas get loaded even in a Read-only or web-only session.
• Redirect deny reasons end with a fail-open suffix: if the bridge tool isn't loaded yet, run
  ToolSearch first; if the native tool is genuinely needed, call it again and it will be allowed
  (critical under headless -p so the agent never hard-stalls).

Set POLYAGENT_HOOK_MODE=nudge for the old non-blocking behavior, or off to disable.
To reset the dedup and see the fires again, start a new session (or delete
polyagent-nudged-<session_id>.json from your OS temp dir — os.tmpdir(),
e.g. /tmp on Linux, not necessarily $TMPDIR).

Preloading at session start (SessionStart)

O PreToolUse cobre buscas via Bash, mas o hook de SessionStart injeta o preload
antes da primeira decisão de ferramenta, independentemente de como o agente busca.

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "node /abs/path/to/polyagent-mcp/hooks/prefer-polyagent.mjs", "timeout": 5 }] }
    ]
  }
}

On SessionStart the hook emits the ToolSearch preload as additionalContext and pre-marks
preload as seen in the session's dedup file, so the PreToolUse piggyback never repeats it.

Reaching subagents too (SubagentStart)

The nudges above only steer the main loop. Spawned subagents never see them,
so wire the same hook for SubagentStart as well:

{
  "hooks": {
    "SubagentStart": [
      {
        "hooks": [
          { "type": "command", "command": "node /abs/path/to/polyagent-mcp/hooks/prefer-polyagent.mjs" }
        ]
      }
    ]
  }
}

On SubagentStart the hook injects a compact polyagent preference into every
spawned subagent via additionalContext (subagentStartContext(agent_type)).
When agent_type is Explore it appends an extra line: that Explore run was spawned on the
orchestrator's expensive model (Explore inherits the session model, capped at Opus), so it should
route all reading through explore/read_slice (which run on GPT-6 Luna) and
keep the expensive shell to orchestration only.

Coexisting with context-mode. The bridge and context-mode use separate channels
(context-mode may still do its own thing; this hook only emits additionalContext),
so they coexist cleanly — no updatedInput race, no delay, no import of
context-mode's routing.

2. Load deferred tools when needed. The five core tools, fast_delegate, fan_out, and
rate are alwaysLoad on Claude Code ≥2.1.121. Older hosts may still defer their schemas. The
secondary tools (generate_image, follow_up, bridge_stats, decide) remain deferred; load only
the ones a task needs. Add to your CLAUDE.md/AGENTS.md:

If a required core schema is missing on an older host, run tool-search for
`delegate, fast_delegate, explore, read_slice, run_filtered, web_lookup, fan_out, rate`.
For secondary tools, load `generate_image`, `follow_up`, `bridge_stats`, or `decide` only when needed.

3. Reconcile the conflict in CLAUDE.md. State the precedence explicitly:

The host rule "prefer dedicated file/search tools" applies to the EDIT path (Edit needs the
file content → native Read). For PURE reading/locating/web (no edit), polyagent takes
precedence over native Read/Grep/Glob/WebSearch/WebFetch. Read a large file whole with native
Read ONLY when you are about to edit it.

4. Delegate execution, not just exploration. The bridge is not only for reading — delegate
runs implementation work with full read/edit/shell access, so the orchestrator shouldn't burn its
own tokens on self-contained tasks. State this in CLAUDE.md so the agent routes doing, not just
finding, to the cheap worker:

You are the ORCHESTRATOR. delegate(prompt, level) is the DEFAULT for BOTH execution AND judgment.
`level` is required: low=GPT-6 Luna max (codex), middle=GPT-6.1 Sol medium (codex),
high=Claude Opus 5.5 high (claude). Numeric levels are rejected. Low/middle cover most work;
high is expensive and shares the Claude Code host subscription, so reserve it for tasks cheaper
levels cannot do. Exhausted Codex quota removes low/middle; exhausted Claude quota removes high
and affects that host together. The worker has full read/edit/shell access
in cwd when you delegate. The constant win is context economy: the worker's raw output never enters
your context. Delegate it, then review the result; edit inline only for a quick one-off you're
already positioned for. Use fast_delegate(prompt) when the work is self-contained and you just want
the fastest healthy worker. Pass agent:"name" or agent:{prompt:"..."} when the worker
needs a specialized persona.

The AA cost ladder (quota proxies, not per-call bills) is $0.07 → $0.21 (~3×) → $1.82 (~8.7×).
See the three-level decision.

Develop

npm test       # vitest — unit tests for model resolution / arg building
npm run dev    # run from source via tsx

License

MIT