codex-subagents

Codex Subagents

Use the codex-subagents MCP server like Claude's native Task tool when the task benefits from an independent OpenAI Codex worker inside Claude Code. If the user asks to "use Codex", "ask Codex", "launch Codex subagents", "use Spark", "get a Codex second opinion", or "run parallel Codex agents", call the MCP tools directly. Do not wait for the user to name the MCP tool.

Default behavior:

• Launches one-shot Codex work through codex exec; persistent sessions use codex app-server --listen stdio:// by default for real live steering. The app-server child is owned by the MCP server process, so no external background daemon is required.
• Prefers the Codex desktop app binary at /Applications/Codex.app/Contents/Resources/codex when it exists.
• Runs Codex in read-only sandbox mode unless the user explicitly requests a different sandbox.
• Uses non-interactive approvals so write or privileged operations fail instead of prompting.
• Supports explicit non-sandbox/full-access execution with full_access: true, which maps to Codex's --dangerously-bypass-approvals-and-sandbox flag and allows DNS/network plus unrestricted file and git writes.
• Lets the caller set model, reasoning effort, project directory, timeout, and parallelism per agent. Put uncommon settings under advanced.
• Supports advanced.model: "spark" for Codex Spark (gpt-5.3-codex-spark) without requiring Claude to remember the exact model string.
• Supports nested Codex subagents by passing advanced.codex_subagents, advanced.subagent_tasks, and advanced.subagent_runtime; custom agents are sent as Codex agents.<name>... config overrides for the child run.
• Supports persistent Codex sessions through the session_id returned by codex_task and codex_task_group; use codex_followup to continue, steer, wait on, cancel, or otherwise manage the same Codex context.
• Supports codex_wait_any for harvesting whichever background Codex session finishes first when Claude launched several sessions in parallel.
• Supports structured results with advanced.output_contract or advanced.output_schema; use these when Claude must merge, compare, or aggregate Codex outputs.
• Redacts secret-looking output by default and does not forward secret-looking environment variables unless forward_sensitive_env is explicitly true.
• Compacts large tool responses before returning them to Claude; when mcpResponse.compacted is true, use the returned summary first and inspect server logs only if the omitted raw tail is necessary.

Prefer the native Claude-like tools for normal use:

• For one delegated task, call codex_task. Provide description like Claude's Task description and prompt as the self-contained task. For code review and exploration, ask for concise findings with file paths and line references.
• For independent tasks that can run concurrently, call codex_task_group with one task object per workstream. Split by ownership such as API flow, tests, security, performance, UI, docs, or migration risk. Keep tasks concrete and bounded, and set max_parallel to the smaller of the useful agent count and 4 unless the user asks for more.
• For multi-turn Codex work, call codex_task for the initial prompt and preserve the returned session_id. Use codex_followup with mode: "queue" for ordinary follow-ups, mode: "wait" when Claude needs completion, mode: "steer" for active redirection, and mode: "cancel" when the user no longer wants the run.
• For several background Codex sessions, use codex_wait_any with all known session_id values instead of polling each session one at a time. Repeat with the returned remaining ids until all work is complete.
• Use codex_followup mode steer only when the user wants to redirect active work now. It delivers real live steering with Codex turn/steer when app-server support is active. Set interrupt_current: true only when the active turn should be cancelled and redirected.
• If unsure which path fits, call codex_task or codex_followup first; use MCP resources only for diagnostics or when a tool response explicitly says to inspect a resource.