subagent-mcp

Core Premise

subagent-mcp is an MCP stdio server that turns an AI coding assistant (Claude Code, Codex, Gemini CLI) into a manager of local Claude and Codex sub-agents on macOS, Linux, and Windows. It orchestrates the locally authenticated claude and codex CLIs you already signed into, and can route tasks to direct API providers (Claude Messages API and OpenAI-compatible) configured in providers.jsonc. Provider credentials stay out of config: providers.jsonc names env vars, and key values live in the adjacent gitignored .env. API HTTP is confined to src/providers/provider-client.ts.

7 h 38 min one-shot coding session, several hundred tool calls, Fable 5, July 15 2026 - 41% context used, no auto-compaction, orchestrated via subagent-mcp.

The orchestrator monitors but does not read or write project files itself. Work is delegated to fresh sub-agents, so the orchestrator keeps summaries instead of raw file context. The main invariants are:

• one machine-global, provider-agnostic concurrency cap (default 20, minimum 10)
• fail-safe orchestration ON on hookless hosts
• state authority only from harness-verified <subagent-mcp state="..."> tags
• launch_agent as the only supported sub-agent launch channel in both states
• setup/init defense-in-depth suppression for known native host agent launchers
• sub-agents gated by default with permission ceiling auto
• automatic model, provider, and effort routing per task category

Install

What You Need First

• Node.js 20 or newer (node --version)
• claude CLI, installed and signed in (claude --version)
• codex CLI, installed and signed in (codex --version; optional if you only use Claude or Gemini as the host)

Building from source needs extra developer tools. See CONTRIBUTING.md.

Install The Package

Marketplace plugin for Claude Code:

claude plugin marketplace add Heretyc/subagent-mcp
claude plugin install subagent-mcp@subagent-mcp

Marketplace plugin for Codex:

codex plugin marketplace add Heretyc/subagent-mcp
codex plugin add subagent-mcp@subagent-mcp

Or Codex MCP registration:

codex mcp add subagent-mcp -- node /abs/path/to/subagent-mcp/dist/index.js

Or install the npm package globally:

npm install -g @heretyc/subagent-mcp

Organizations pinning the package through GitHub Packages should see docs/registration/prerequisites-and-install.md.

Wire It Into Your Assistant

subagent-mcp setup

Installing the package only ships the program. It does not connect anything on its own. subagent-mcp setup finds your Claude Code, Codex, or Gemini install and registers the supported server, hook, and native-agent suppression config for that host. For Claude Code it also registers or wraps statusLine so the hook can read Claude's authoritative context percentage without replacing your custom statusline, writes settings.json env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE = "90", and deploys the smcp-handoff Agent Skill to your Claude user scope. Preview first with subagent-mcp setup --dry-run.

For provider config, run subagent-mcp config init, edit the generated .env keys under your subagent-mcp config home, then run subagent-mcp config validate. See skills/smcp-help/SKILL.md for details. Once the server is running, use the configure MCP tool (or the /smcp:config skill) to list, read, or update settings by canonical key without leaving the assistant.

Restart, Then Turn On The Invariant

Restart your Claude Code or Codex session so it picks up the new tools. On Codex, run /hooks and trust the new hook. Then, recommended:

subagent-mcp init --global

This writes a managed "always delegate" rule block into your global assistant config once. For one project only, use subagent-mcp init --root /path/to/project. Full per-platform wiring (Gemini CLI, Claude Desktop, manual setup) is in docs/registration.md.

Operation guide (tools, swarms, concurrency): README/operation.md.

Configuration

Machine-wide defaults live in global-subagent-mcp-config.jsonc, installed beside the compiled server and re-read on every launch_agent. It controls the global concurrency cap, update checks, permission ceiling, escalation behavior, strict read-parity logging, and Codex sandbox networking.

Context-coaching preferences live only in ~/.subagent-mcp/settings.json (or settings.local.json): contextCoaching defaults to true. When enabled, the hook delivers optional per-turn planning and goal-capture coaching. Disabling it suppresses that coaching only; mandatory lifecycle injections (handoff preparation at 80%, compaction detection, and the one-turn read mandate) fire regardless.

User and repo permission files can only tighten or add scoped permissions on top of the global ceiling. See README/configuration.md for the full key table, precedence rules, and mode summary.

Context and Handoff Lifecycle

The implemented Claude and Codex hooks track context utilization each turn. At 80% they mandate a fresh handoff write: a record with version = 2, lifecycle = "prepared", and a random generation ID. This sits 10 points before the 90% auto-compaction boundary, ensuring a current snapshot exists before compaction clears context.

Compaction detection runs on the same per-turn path as all other metering. A drop of 10 or more percentage points from a prior sample at or above 80%, within the same session, is necessary but not sufficient: the current sample must ALSO carry a fresh structural compaction-generation proof. For Claude that proof comes only from the newest main-chain system compact_boundary: that exact boundary must have compactMetadata.trigger = "auto" and a canonical top-level UUID. A newer manual or invalid boundary masks every older valid auto boundary. For Codex it is a freshly compacted context-window identity (window_id / window_number). Codex exposes no auto-versus-manual cause, so a manual /compact at or above 80% with a qualifying drop is indistinguishable and does trigger. The last-seen generation persists in the metering record, so an unchanged proof is rejected as a replay and each compaction fires the lifecycle at most once. Pairs that fail session, harness, source, model, context-window, sample-sequence, freshness, current-sample, or sub-agent checks are rebaselined, not flagged.

On confirmed compaction the record enters session_handoff_required. The hook then injects a one-turn handoff-read mandate exactly once and moves the record to resuming. Automatic transition eligibility requires all four runtime predicates: version = 2, lifecycle = "prepared", a non-empty generation, and created_by_session matching the current session. Other readable records are ineligible for that automatic transition. After a successful handoff-read, the caller must ask exactly four structured confirmation questions before acting. With a current session key, the read stamps the reader fields and moves any version-2 record to working; readable records with another or no version retain their lifecycle schema.

Enforcement is directive-only: no tool-level gates are added in any lifecycle state.

Permissions

Launched sub-agents run gated by default. Set permissionsCeiling in global-subagent-mcp-config.jsonc:

When a sub-agent's action parks, its status becomes permission_requested and it appears in poll_agent, list_agents, and wait. Answer it with:

respond_permission(agent_id="...", decision="allow" | "deny", reason="...")

One-time only. Omit request_id to answer the oldest pending request. Unanswered requests auto-deny after 5 minutes. Full spec: docs/spec/permissions.md.

Basic Debugging

• An agent looks stuck. A quiet agent is usually still alive. After about 10 minutes with no output an agent is marked stalled. Prefer wait or another poll_agent over killing it.
• Cap reached. Use list_agents to see what is running and kill_agent on work you no longer need. Raising globalConcurrentSubagents also works.
• Logs. Agent output is available through poll_agent. Server diagnostics go to the host MCP server log on stderr.
• Install or config looks wrong. Run subagent-mcp doctor for the diagnostic suite; it prompts before any fix. subagent-mcp rollback restores the most recent config backup. See skills/smcp-doctor/SKILL.md.

Documentation

License

Apache-2.0. Copyright 2026 Lexi Blackburn (https://github.com/Heretyc/).

See LICENSE.