# subagent-mcp

[![npm version](https://img.shields.io/npm/v/@heretyc/subagent-mcp?label=npm)](https://www.npmjs.com/package/@heretyc/subagent-mcp)
[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
[![node](https://img.shields.io/node/v/@heretyc/subagent-mcp)](https://www.npmjs.com/package/@heretyc/subagent-mcp)
[![CI](https://github.com/Heretyc/subagent-mcp/actions/workflows/claude-routine.yml/badge.svg)](https://github.com/Heretyc/subagent-mcp/actions/workflows/claude-routine.yml)

## 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`.

![subagent-mcp long-horizon session demonstration](docs/images/smcp-example.png)

*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](CONTRIBUTING.md).

### Install The Package

Marketplace plugin for Claude Code:

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

Marketplace plugin for Codex:

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

Or Codex MCP registration:

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

Or install the npm package globally:

```bash
npm install -g @heretyc/subagent-mcp
```

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

### Wire It Into Your Assistant

```bash
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](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:

```bash
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](docs/registration.md).

Operation guide (tools, swarms, concurrency): [README/operation.md](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](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`:

| Mode | What a sub-agent can do |
|---|---|
| `auto` | Default. Safe reads auto-allow, dangerous actions auto-deny, everything else parks for your decision. |
| `manual` | Same, but every non-denied action parks for a decision. |
| `yolo` | No gating at all. |

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:

```text
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](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](skills/smcp-doctor/SKILL.md).

## Documentation

| Document | Contents |
|---|---|
| [docs/spec/arch-rationale.md](docs/spec/arch-rationale.md) | Design rationale |
| [docs/registration.md](docs/registration.md) | Per-platform setup |
| [docs/install/_INDEX.md](docs/install/_INDEX.md) | Install guide map |
| [docs/tools.md](docs/tools.md) | Tool reference |
| [docs/usage.md](docs/usage.md) | Model and effort matrix |
| [docs/SPEC.md](docs/SPEC.md) | Technical specification |
| [README/configuration.md](README/configuration.md) | Configuration keys and precedence |
| [docs/spec/permissions.md](docs/spec/permissions.md) | Permission system |
| [docs/reference/status-lifecycle.md](docs/reference/status-lifecycle.md) | Agent status meanings |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Developer guide |

## License

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

See [LICENSE](LICENSE).