subturn

Run subagents in any coding agent you have installed, from any MCP client. You pick the harness and model, it handles the rest.

It is an MCP server. A coding agent calls it with a harness, a model and effort, a prompt, and a working directory; Subturn starts a session in that harness with the logins you already have, hands back the harness's own session id, and the caller collects the answer later. Codex, Claude Code, Grok, and OpenCode are supported today. The npm package, the MCP server name, and the CLI binary are all called subturn. Why it is shaped this way is in AGENTS.md.

Install and wire up

The MCP server is a stdio process. Any host that can run a command as an MCP server can run it via npx:

claude mcp add subturn -- npx -y subturn serve      # Claude Code
codex mcp add subturn -- npx -y subturn serve       # Codex

For hosts configured by file, the entry is the same command:

{ "command": "npx", "args": ["-y", "subturn", "serve"] }

npx -y fetches the package on first use, which can trip a host's MCP start-up timeout on a cold machine. When that matters, install once and point the host at the binary:

npm install -g subturn
claude mcp add subturn -- subturn serve

Requires Node 22.13 or newer, and OpenCode 2.0.25 or newer for that harness. Until the package is published, npx github:eshatalov/subturn works the same way. From a checkout, npm install builds dist/ and the server is node dist/faces/mcp.js.

Related MCP server: agentmux

The caller's whole manual

An orchestrator needs one instruction file to use Subturn. Most of it is a paragraph saying how to call the five tools. It is the same in every project, and it is the whole surface Subturn exposes; we keep it that size on purpose. Which model to use for which kind of work depends on the user's subscriptions and taste, so that part is the owner's to write, and Subturn never gets in its way.

Here is a whole file, as an example. Give it the same scope as the server: your host's user-level instructions (~/.claude/CLAUDE.md for Claude Code, ~/.codex/AGENTS.md for Codex) when the server is installed for every project, the project's own instruction file when it is installed for one. The last paragraph names the models one particular setup uses, with glm and muse showing how other subscriptions come in through OpenCode; replace it with yours.

Delegate through the `subturn` MCP server. Never call the harness CLIs from Bash.

Spawn with a harness (`claude`, `codex`, `grok`, `opencode`), a full model id and a reasoning effort (both passed verbatim), a prompt, and an absolute cwd. After the few seconds the harness needs to come up you get its own session id back while the subagent runs on; if anything fails before the session exists, the spawn itself errors with the full detail inline. `await` the id for the outcome, waiting up to `timeout` seconds (default and max 300, `0` for a snapshot; the turn keeps running if the wait runs out): final text, usage, and the model and effort the harness acknowledged on success, bare `failed` or `cancelled` otherwise. `resume` the id with a new prompt to continue the conversation once its turn is no longer running; harness, model, effort, and cwd carry over, the id stays the same, and the conversation stays resumable for 7 days after its last turn. `cancel` kills a running turn and keeps the session. Every "why" is in `inspect`, which returns the raw evidence and works mid-run. Turns die at their deadline (default 3600 s), so fire-and-forget is safe; fan-out is just several spawns. Give the subagent a disposable cwd or worktree when cleanliness matters and diff it afterwards.

- The prompt is all the subagent sees. Put everything it needs in it.
- Subagents cannot delegate further. Cross-checks and reviews are separate spawns from here.
- Retries and fallbacks are yours. On `failed`, read `inspect` before trying again.
- Always pass the effort.

`fable` = claude `fable`, `opus` = claude `opus`, `sonnet` = claude `sonnet`, `haiku` = claude `haiku`, `grok` = grok `grok-4.7`, `glm` = opencode `zai-coding-plan/glm-5.3`, `muse` = opencode `opencode-go/muse-spark-1.3-contributor`. Model ids are fixed, don't look for replacements. For `astra`, `sol` and `luna` don't use MCP, use native subagents instead.

CLI

The same binary is a CLI with the same verbs, plus human-only extras:

subturn spawn --harness opencode --model zai-coding-plan/glm-5.3 \
    --effort high --cwd /tmp/scratch --prompt "Reply with exactly: ok"
subturn await <session-id> --timeout 120
subturn resume <session-id> --prompt "And now do the next thing"
subturn cancel <session-id>
subturn inspect <session-id>
subturn status     # what is installed and logged in, advertised models; probes only
subturn prune      # delete every session not running now, without waiting out the 7 days
subturn serve      # the MCP stdio server

CLI spawn and resume detach a per-turn supervisor, so the one-shot invocation exits while the subagent runs.

How it works

Core (src/core) has five functions, one per verb. Admission runs before any quota is spent: a persisted per-harness pin (the newest copy of the binary on PATH or in the usual install dirs, re-probed when that set of files changes) and a cheap auth check that never launches the harness (Codex's auth.json tokens, the macOS keychain item for Claude Code, Grok's auth file, the credential table in OpenCode's database). A spawn that dies before the harness produces a session id throws a plain error carrying the auth result, argv, stderr, and exit inline. Model ids are never gated: a wrong one fails inside the harness and comes back as evidence.

Sessions live under ~/.local/state/subturn/sessions/<session-id>/ (SUBTURN_STATE_DIR overrides). The directory holds the record, the prompt, the spawn command, the event stream as it happens, stderr, the acknowledged bundle where the harness echoes one, and the final text, so inspect works on a running session. Retention is 7 days after the last turn (SUBTURN_RETENTION_DAYS), swept on each spawn or on demand by prune; the resume window is the retention window, because the harness state needed for resume lives in the same directory. The deadline default is 3600 s (SUBTURN_DEADLINE_S), the maximum six hours.

Supervisor (src/core/supervisor.ts) runs every turn in its own detached process, so neither an MCP server restart nor a one-shot CLI exit can orphan a run. It publishes the native id the moment the harness reports it, reaps at the deadline or on cancel through one kill path (the harness child and every process it spawned, since tool shells often sit in their own process group), runs the plugin's hygiene, and absorbs id rotation on resume by keeping the old id resolvable.

Faces (src/faces) are single files over the core. The interface is defined once as data in interface.ts; the MCP server and the CLI both derive from it, so they cannot drift. The MCP server holds no state and loads the core on the first tool call, since it sits in every host session and most never spawn. Unknown parameters are refused by the verb table itself.

Plugins (src/plugins) answer a small interface per harness: detection hints, auth, advertised models, shadow home, launch, and post-turn hygiene. Adding a harness is one entry in the registry; plugin modules load on first use.

Every plugin launches its harness in a validated permissive posture (--dangerously-bypass-approvals-and-sandbox, --dangerously-skip-permissions, --always-approve, or Subturn's own allow-everything ACP permission handler). Concurrent sessions of one harness do not collide: shadow state is per session.

Development

npm run typecheck   # src + tests
npm test            # scripted fake agent, offline, temp state dir; touches no real harness
npm run build       # dist/, what the faces run from

Tests need Node 22.18 or newer, since they run the TypeScript sources through Node's own type stripping. They drive the full path (spawn, detached supervisor, ACP client, evidence, resume, await) against test/fake-agent.mjs, including replay isolation on resume, the sequential-turn guard, id-rotation absorption, and claude parking on a temp config dir.

Live tests spend real quota and are gated:

SUBTURN_LIVE=1 node --test test/live.test.ts                      # smoke + resume, two tiny turns
SUBTURN_LIVE=1 SUBTURN_LIVE_KILL=1 node --test test/live.test.ts     # resume after a deadline kill
SUBTURN_LIVE=1 SUBTURN_LIVE_CANCEL=1 node --test test/live.test.ts   # cancel mid-turn, then resume

SUBTURN_LIVE_HARNESS picks the harness (default opencode); each harness has a cheap default bundle, and SUBTURN_LIVE_MODEL with SUBTURN_LIVE_EFFORT override it.