codex-specialized-subagents

This MCP server provides artifact-first sub-agent delegation for Codex CLI. It exposes three tools: delegate_autopilot, which orchestrates multiple specialist sub-agent runs to tackle a multi-step task; delegate_run, which executes a single specialist sub-agent via codex exec; and delegate_resume, which resumes a previously started sub-agent thread. Each invocation writes a detailed run directory under CODEX_HOME (defaulting to $HOME/.codex)/delegator/runs/<run_id>/ that stores prompts, chosen skills, event streams, and structured results to aid debugging and auditing of artifacts.

In practice, you can use delegate_autopilot to break a complex request into jobs (scan, implement, verify) and run the relevant codex exec sub-agents in parallel or sequence. If you prefer explicit control, delegate_run lets you trigger a particular specialist sub-agent with configurable reasoning effort or config overrides, while delegate_resume can continue work on an interrupted thread. This setup is designed to give you durable artifacts and better parallelism for multi-step, cross-cutting tasks such as refactoring, auditing, or comprehensive documentation generation.

Prerequisites:

• Node.js version >= 20
• npm
• mise (recommended for pinned runtime)
• codex CLI on PATH and authenticated
• Optional Python 3 for helper scripts

From the repository root:

1. Install the pinned runtime (recommended):

mise install

2. Run the drift check to ensure lockfiles and pins are correct:

./toolchain-check.sh

3. Install dependencies from the lockfile and build:

npm ci
npm run build

4. (Optional) Configure Codex for longer tool timeouts if delegated runs may take minutes:

• Create the Codex MCP server config as described in the README and set tool_timeout_sec to a suitable value (e.g., 1200).

5. Register the MCP server with Codex (example):

codex mcp add codex-specialized-subagents \
  --env CODEX_AUTOPILOT_REASONING_EFFORT_LOW=low \
  --env CODEX_AUTOPILOT_REASONING_EFFORT_MEDIUM=medium \
  --env CODEX_AUTOPILOT_REASONING_EFFORT_HIGH=high \
  -- node "$(pwd)/dist/cli.js"

6. Verify the MCP server is registered:

codex mcp get codex-specialized-subagents

Notes and tips:

• Ensure Codex is authenticated and available on PATH for delegated runs.
• Run directories under ${CODEX_HOME:-$HOME/.codex}/delegator/runs contain prompts, selected skills, event streams, and results; treat these as sensitive artifacts.
• If you see TOML-related errors when configuring tool timeouts, keep a single [mcp_servers.codex-specialized-subagents] section in your $HOME/.codex/config.toml and only adjust tool_timeout_sec inside it.
• The server is designed for artifact-first workflows; use it when durable logs and outputs help debugging or auditing delegation outcomes.
• The optional Python helper scripts under .agent/ may be used for additional tooling but are not required for core operation.