codex-specialized-subagents
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
codex-specialized-subagents
Artifact-first sub-agent delegation for Codex CLI (MCP server).
This repo provides a local (stdio) MCP server that exposes:
delegate_autopilot— decide whether to delegate and, if yes, orchestrate one or morecodex execsub-agent runsdelegate_run— run a single specialist sub-agent viacodex execdelegate_resume— resume a prior sub-agent thread viacodex exec resume
Each tool call writes a run directory under ${CODEX_HOME:-$HOME/.codex}/delegator/runs/<run_id>/ containing the prompt, selected skills, event stream, and structured results (artifact-first debugging).
When to use
You want parallelism and specialization for multi-step / cross-cutting work.
You want durable artifacts (logs + outputs) to debug and review what happened.
Related MCP server: Roundtable AI MCP Server
Requirements
Node.js
>=20(seepackage.json#engines)npmmise(recommended): installs the pinned runtime frommise.tomlcodexCLI on your PATH and authenticated (required for real delegation runs)
Optional:
Python 3 (only for helper scripts under
.agent/)
Install & quickstart (from source)
From the repo root (installs deps + builds dist/):
# Recommended: install the pinned runtime (see mise.toml)
mise install
# Drift check (lockfiles + pins)
./toolchain-check.sh
# Install deps from lockfile
npm ci
# Build
npm run buildConfigure Codex (recommended, prevents timeouts)
Delegated runs can take minutes. Set this server’s MCP tool timeout to 1200 seconds (20 minutes) in your Codex config ($HOME/.codex/config.toml):
mkdir -p "$HOME/.codex"
cat >> "$HOME/.codex/config.toml" <<'EOF'
[mcp_servers.codex-specialized-subagents]
tool_timeout_sec = 1200
EOFIf you already have a [mcp_servers.codex-specialized-subagents] section, edit the existing tool_timeout_sec instead of appending a duplicate.
Common gotcha: tool_timeout_sec is not an env var. If you put it under mcp_servers.codex-specialized-subagents.env.*, Codex will error with “expected a string” (env values must be strings).
If you see a TOML parse error about a “duplicate key” for [mcp_servers.codex-specialized-subagents], you have that table declared twice — keep only one header and put tool_timeout_sec = 1200 inside it.
Register with Codex (recommended defaults)
From the repo root (includes per-job reasoning-effort overrides for delegate_autopilot):
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"Verify:
codex mcp get codex-specialized-subagentsRemove:
codex mcp remove codex-specialized-subagentsUsage
Interactive autopilot (recommended)
In Codex interactive mode, delegate_autopilot can split a request into jobs (scan / implement / verify) and run specialist sub-agents.
To make delegation feel automatic in interactive mode, install the included delegation-autopilot skill globally:
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/delegation-autopilot"
cp .codex/skills/delegation-autopilot/SKILL.md \
"${CODEX_HOME:-$HOME/.codex}/skills/delegation-autopilot/SKILL.md"Then try prompts like:
“Refactor the MCP server and update tests + README.”
“Audit the repo docs and propose improvements.”
Optional: delegate_autopilot assigns each job a thinking_level (low | medium | high). You can set CODEX_AUTOPILOT_REASONING_EFFORT_LOW|MEDIUM|HIGH on the MCP server process to override Codex model_reasoning_effort per job (see docs/usage.md). (Legacy/advanced: CODEX_AUTOPILOT_MODEL_LOW|MEDIUM|HIGH overrides model name.)
Manual tool calls
If you prefer explicit tool usage, tell Codex to call one of:
delegate_autopilot(multi-agent orchestration)delegate_run(single sub-agent run)delegate_resume(resume a prior sub-agent thread)
Optional (advanced): for delegate_run / delegate_resume, you can pass reasoning_effort (maps to codex exec -c model_reasoning_effort="...") or raw config_overrides (maps to codex exec -c <override>). If you want a default for manual runs, set CODEX_DELEGATE_REASONING_EFFORT on the MCP server process (only applies when reasoning_effort is omitted and config_overrides does not already set model_reasoning_effort).
Skills
Sub-agent runs can load Codex skills from:
repo-local
.codex/skills(nearest ancestor of the delegatedcwd)global
${CODEX_HOME:-$HOME/.codex}/skills
Note: this repo’s delegation-autopilot skill is marked delegator_exclude: true (parent-only) to prevent delegation recursion.
Artifacts (run directories)
Each tool call writes a run directory under ${CODEX_HOME:-$HOME/.codex}/delegator/runs/<run_id>/.
Documentation
Start with docs/README.md (index), then:
docs/usage.md— how to use the tools effectivelydocs/troubleshooting.md— common failure modes (timeouts, missingcodex, etc.)docs/development.md— local development and test matrixdocs/reference/tools.md— full tool schemas (inputs/outputs)docs/reference/run-directories.md— run directory layout and artifact meaning
Development
npm test
npm run lint
npm run devIntegration tests (requires Codex CLI + auth):
RUN_CODEX_INTEGRATION_TESTS=1 npm testContributing: CONTRIBUTING.md.
Security
Don’t commit secrets (
.envis gitignored; use.env.exampleas a template).Run directories can contain sensitive prompts/output; treat
${CODEX_HOME:-$HOME/.codex}/delegator/runsas sensitive.
Reporting: SECURITY.md.
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
AI-powered spec-to-task decomposition and execution orchestration for coding agents.
Coordination hub for AI coding agents: message teammates, ask humans, audit every event.
Shared task layer for AI agents: tasks, handoffs and decisions that persist across tools.
Multi-agent coordination outside your LLM context: dedupe parallel work, per-agent budgets, handoff
Related MCP Servers
- FlicenseNot gradedqualityAmaintenanceEnables a primary coding assistant to delegate tasks in parallel to specialized local sub-agents, sharing project context and synthesizing their responses into a single result.-
- FlicenseNot gradedqualityAmaintenanceEnables a primary AI coding assistant to delegate tasks in parallel to specialized CLI-based AI sub-agents, sharing project context and synthesizing their responses from within an IDE.-
- FlicenseNot gradedqualityAmaintenanceEnables a primary AI coding assistant to delegate tasks to specialized sub-agents in parallel, share project context, and synthesize their responses. It uses existing local CLI tools and API subscriptions to coordinate Codex, Claude, Cursor, and Gemini without extra cost.-
- FlicenseNot gradedqualityAmaintenanceEnables a primary AI assistant in an IDE to delegate tasks to specialized CLI-based sub-agents such as Gemini, Claude, Codex, and Cursor, with shared context, parallel execution, and synthesized responses.-