subagent-cockpit-mcp

One MCP server, six coding agents from six vendors: OpenAI Codex, Claude Code, Grok, OpenCode, Google Antigravity and Pi.

Let the agent you already use (Claude Code, Codex CLI, Cursor, any MCP client) hand work to the other coding agents on your machine. One writes the code, the others review it, test it and draft the release notes.

• Mix vendors. Each role gets the agent and model that suits it, all behind the same 17 tools.

• Work in parallel. prompt(wait: false) sends tasks to several agents at once, status and output collect the results.

• Keep context. Review findings go back to the session that wrote the code. Reconnect to a session by id days later.

• Stay in charge. Approvals and questions come back to the main agent, and allow lasts for one session only.

• No screen scraping. Every agent runs over the Agent Client Protocol (ACP).

• Watch it live. A read-only page at http://127.0.0.1:7200 shows every session as it runs.

Web UI

Open http://127.0.0.1:7200 to watch the sessions: replies as they stream, tool calls with their diffs, plans, approvals and questions, plus a protocol log of every raw ACP message.

• Read-only. The page watches and never acts. Approvals and answers still go through the tools.

• Starts and stops by itself. The first MCP server that finds the port free starts it, and every server on the machine reports to the same page. It exits about 10 seconds after the last server goes away.

• Memory only. Nothing is written to disk. A web UI started again shows the sessions that are still open, not the old messages.

• Port. "webui": { "port": 7200 } in the config, or SUBAGENT_COCKPIT_WEBUI_PORT, which wins. 0 turns it off. When another program holds the port, the server says so on stderr and runs without the web UI.

• Privacy. The page shows the ACP messages as sent, prompts and args included. It listens on 127.0.0.1 only, but other users of the same machine can open it.

• Font. The conversation tab is monospace. Install Sarasa Mono SC (or Noto Sans Mono CJK SC) and Chinese lines up with Latin text at exactly two columns per character; without it Chinese falls back to the system font.

Related MCP server: subturn

Quick start

1. Install Node.js 22+ and the agents you want, and log in to each. The server never downloads them.

   Agent	Version	Install
   OpenAI Codex	0.160.1+	brew install --cask codex or npm i -g @openai/codex
   Anthropic Claude Code	2.1.292+	brew install --cask claude-code or the official installer
   xAI Grok Build	1.0.46+	brew install --cask grok-build
   OpenCode	2.0.30+	brew install opencode (the 1.x opencode-ai on npm is not supported)
   Google Antigravity	1.4.2+	brew install --cask antigravity-cli, then run agy once to sign in
   Earendil Pi	1.4.0+	brew install pi-coding-agent or npm i -g @earendil-works/pi-coding-agent (Node 22.19+), then run pi and /login, or give it a provider key in env

2. Add the server to your MCP client:

   claude mcp add subagent-cockpit -- npx -y subagent-cockpit-mcp

   Claude Code asks before each MCP tool call. To let it drive the subagents without asking, allow the whole server in ~/.claude/settings.json or the project's .claude/settings.json:

   { "permissions": { "allow": ["mcp__subagent-cockpit"] } }

   Codex CLI (~/.codex/config.toml):

   [mcp_servers.subagent-cockpit]
   command = "npx"
   args = ["-y", "subagent-cockpit-mcp"]
   tool_timeout_sec = 1800                  # default 60, longer means fewer status checks
   default_tools_approval_mode = "approve"  # needed for `codex exec`

   Cursor (.cursor/mcp.json or ~/.cursor/mcp.json):

   { "mcpServers": { "subagent-cockpit": { "command": "npx", "args": ["-y", "subagent-cockpit-mcp"] } } }

3. Give each agent a role in ~/.subagent-cockpit/config.json (created on first start):

   "subagents": {
     "coder":    { "adapter": "codex",       "role": "You implement changes in this repository." },
     "reviewer": { "adapter": "claude",      "mode": "plan", "role": "You review diffs. Report findings, do not edit files." },
     "security": { "adapter": "grok",        "role": "You look for security issues in diffs. Do not edit files." },
     "tester":   { "adapter": "opencode",    "role": "You run the test suite and report failures." },
     "docs":     { "adapter": "antigravity", "model": "gemini-3.8-flash", "role": "You draft release notes as text. Do not edit files." },
     "unit":     { "adapter": "pi",          "model": "anthropic/claude-sonnet-5-5", "role": "You write unit tests for new code." }
   }

4. Ask your main agent:

   Use subagent-cockpit. Have the coder add rate limiting to the API and the unit subagent write tests for it. Have the reviewer and the security subagent review the diff, and send their findings back to the coder until both pass. Then have the tester run npm test, ask the docs subagent for release notes, and report.

Supported agents

Verified with codex 0.162.1, claude 2.1.292, grok 1.0.46, opencode 2.0.30, agy 1.4.3 and pi 1.4.0. There is no upper version bound. A release that breaks the protocol fails with AGENT_ERROR until the server is updated. This is the ACP rewrite of subagent-cli.

Tools

prompt, approve, allow, reject and answer wait as long as the turn takes and return done with the output, approval_needed or question_needed. Pass wait: false to return right away. The server never times out a turn. If your client gives up first, the turn keeps running, and status and output pick it up.

open with reuse: true takes an idle session of this server with the same cwd and subagent, else reconnects the latest closed one on disk. If that one cannot be reconnected, you get a new session and a reuse_skipped note, and the broken one is not picked again.

snapshot returns the conversation exactly as the Web UI shows it: prompts, replies, thinking, tool calls with their input, output and diffs, plans, approvals, questions and agent-specific messages, one item each, plus every session's state and pending notifications. Narrow it down when you only need part of it:

{ "session": "codex_019a…", "types": ["tool"], "last": 5 }
{ "session": "codex_019a…", "exclude_types": ["thought", "raw"] }
{ "since": 1287, "server_id": "f3c1…" }

types keeps and exclude_types drops item kinds (prompt, message, thought, tool, plan, turn and the rest), last takes the last few, and since with the seq and server_id of the previous call returns only what changed. reset: true means start over from the items returned.

A UI client that polls passes simplify: true. Tool calls then come with their title, status and paths only, and each session without its slash commands. It fetches the rest of one item when the person opens it:

{ "simplify": true, "since": 1287, "server_id": "f3c1…" }
{ "session": "codex_019a…", "id": "tool:call_2" }

The second line is the item call. An item that is no longer kept fails with ITEM_NOT_FOUND.

Configuration

~/.subagent-cockpit/config.json is created on first start with one entry per agent. An entry using every field:

{
  "idle": { "timeout": 0 },
  "webui": { "port": 7200 },
  "subagents": {
    "reviewer": {
      "adapter": "claude",
      "description": "Reviews diffs",
      "role": "You review diffs. Report findings, do not edit files.",
      "model": "opus",
      "reasoning_effort": "high",
      "mode": "plan",
      "path": "/opt/homebrew/bin/claude",
      "args": ["--add-dir", "/data"],
      "env": { "CLAUDE_CONFIG_DIR": "/path/to/claude-config", "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}" }
    }
  }
}

A subagents object you write replaces the default entries as a whole. idle.timeout closes sessions idle that many seconds. The default 0 never closes them, since the server and its agents exit with your MCP client anyway. A session closed this way comes back by itself on the next prompt or set_config, settings included; status meanwhile reports it CLOSED. webui.port is the Web UI port, 0 for none. SUBAGENT_COCKPIT_HOME moves the whole ~/.subagent-cockpit directory.

The Web UI and snapshot keep the latest 5000 ACP messages per session, and show any message over 1 MB (1048576 bytes) as a truncation marker. Each has its own setting, in bytes and counts:

{
  "webui": { "port": 7200, "truncate_message_size": 1048576, "max_message_count": 5000 },
  "snapshot": { "truncate_message_size": 1048576, "max_message_count": 5000 }
}

Conversation items go with the messages behind them. The Web UI keeps the max_message_count of the server that started it.

Clients started from a desktop app may hand the server a PATH without /opt/homebrew/bin. Set path then.

Profiles

A profile holds settings that several subagents share. A subagent names it in profile and overrides what it needs:

"profiles": {
  "gateway": { "env": { "ANTHROPIC_BASE_URL": "https://example.com", "ANTHROPIC_AUTH_TOKEN": "${GATEWAY_TOKEN}" } }
},
"subagents": {
  "claude":      { "adapter": "claude", "profile": "gateway" },
  "claude-fast": { "adapter": "claude", "profile": "gateway", "model": "haiku" }
}

Plain fields come from the subagent when set, else from the profile. env merges by name and args by --flag, with the subagent winning. A profile cannot name another profile, and a missing one fails with PROFILE_NOT_FOUND.

Credentials and gateways

The server never logs in and never stores credentials. Each agent uses its own login unless the subagent env says otherwise. On AUTH_REQUIRED, log in with the agent's CLI or fix env.

• Claude Code: ANTHROPIC_API_KEY, or ANTHROPIC_BASE_URL with ANTHROPIC_AUTH_TOKEN. CLAUDE_CONFIG_DIR gives a subagent its own config directory.

• Codex: a custom provider goes in the config.toml of a separate CODEX_HOME, with its key in env, e.g. { "CODEX_HOME": "/path/to/codex-home", "OPENAI_API_KEY": "${MY_KEY}" }. DEFAULT_AUTH_REQUEST makes codex-acp log in by itself and save the key in CODEX_HOME/auth.json.

• Grok: a custom endpoint goes in the config.toml of a separate GROK_HOME, with XAI_API_KEY in env.

• OpenCode: point OPENCODE_CONFIG at a config whose providers.openai.settings sets baseURL and apiKey ({env:VAR}). Add "transport": "http" if the gateway has no WebSocket.

• Antigravity: signs in only from its own terminal UI. For a second account, set HOME in env and run HOME=/path/to/home agy once.

• Pi: /login saves to auth.json under PI_CODING_AGENT_DIR (default ~/.pi/agent). A gateway goes in models.json in the same directory (baseUrl, api and an apiKey such as ${MY_KEY}), with the key in env. Set PI_CODING_AGENT_DIR in env to give a subagent its own config.

What the agents read from your machine

The server passes settings through and never isolates them.

• Claude Code and Grok read your Claude Code settings (including permissions.defaultMode), plugins and hooks. Isolate Claude Code with CLAUDE_CONFIG_DIR, and Grok with another HOME plus an explicit GROK_HOME.

• OpenCode reads your Claude Code skills and CLAUDE.md. OPENCODE_DISABLE_CLAUDE_CODE=1 turns that off.

• Antigravity reads ~/.gemini/antigravity-cli/settings.json (including permissions.allow) under HOME.

• Pi loads skills (also from ~/.agents/skills/ and .agents/skills/), extensions, MCP servers, AGENTS.md and CLAUDE.md. --no-skills, --no-extensions, --no-mcp and --no-context-files in args turn them off.

Notes

• Questions. A question arrives as question_needed with the agent's own form in requested_schema. Field names differ per agent, so read them from the schema and reply with answer({ session, question_id, content: { question_0: "Red" } }). Approvals go first when both wait.

• Approvals. An agent's own "don't ask again" option is usually saved for good, so allow never picks it. It allows the call once and keeps a rule in the server until the session closes. To have the agent remember it anyway, approve with that option: Codex accept_execpolicy_amendment, Claude Code allow-with-updates, Grok always-allow, OpenCode always.

• Deleting. delete removes the server's session directory and the agent's own session. An open Claude Code session is closed first, which takes a few seconds. agy cannot delete a conversation, so it stays under ~/.gemini/antigravity-cli/.

• Antigravity. agy -p is headless and never asks. A tool that needs a permission is denied, reading a file outside the session's cwd included, and the output ends with a note such as agy denied in headless mode: ReadFile. Either allow the action in permissions.allow of ~/.gemini/antigravity-cli/settings.json, in agy's own form such as read_file(<path>), or let that subagent skip agy's checks:

  "docs": { "adapter": "antigravity", "args": ["--dangerously-skip-permissions"] }

• Pi. pi never asks for approval, so every tool it has runs straight away, bash, edit and write included. Limit the tools in args, e.g. ["--tools", "read,grep,find,ls"] for a read-only subagent.

• Client timeouts. Codex CLI times out tool calls after 60 seconds unless tool_timeout_sec is set. Claude Code aborts a call after 30 minutes without progress, and the server sends progress every 60 seconds, so long turns survive.

Development

npm install
npm run build && npm run lint && npm test
npm run test:e2e:codex       # also :claude, :grok, :opencode, :antigravity, :pi, :concurrent
npm run check:deps           # bundled ACP adapters == verified versions

The diagram is hand-written SVG, assets/overview-light.svg and assets/overview-dark.svg. Keep the two in sync. Product names and logos belong to their owners.

License

Apache-2.0