Codex Subagent

codex-subagent-mcp

An MCP server that lets Claude Code delegate coding tasks to OpenAI's Codex CLI running on the same machine, with the model and reasoning depth chosen per task. Claude stays the orchestrator. Codex becomes a subagent it can call.

An independent project. Not affiliated with, endorsed by, or supported by OpenAI or Anthropic.

Quick start

Requires Node.js 22+ and the [Codex CLI](https://developers.openai.com/codex/cli) installed, on PATH, and signed in.

claude mcp add codex-subagent -- npx -y codex-subagent-mcp

Ask Claude to run codex_doctor if anything is missing. See [docs/INSTALL.md](docs/INSTALL.md) for platform setup, Claude Desktop and other installation options, and Safety before enabling writes.

What you get

• You pick the model and the reasoning effort per task, from the catalog your Codex CLI reports live.
• Read-only by default, with a sandbox ceiling no tool call can exceed.
• Every finished delegation checks the model, effort, sandbox and directory it asked for against what Codex recorded for the run, and says when they differ or could not be confirmed.
• Optional output_schema returns JSON that matches your schema, for results Claude can act on directly.
• Cancelling, timing out or shutting down stops Codex and the commands it started that the server can still find; a command that detached from that process tree can outlive it.

A real read-only delegation asking for the package name, captured 2026-09-30:

codex-subagent-mcp

Commands run (1 total):

• [exit 0] /bin/zsh -lc "sed -n '1,80p' package.json"

model=gpt-5.6-luna | effort=low | sandbox=read-only | working_dir=/Users/you/project | applied=confirmed | duration=8s | tokens=in 35701 (cached 28160, uncached 7541) / out 88 (reasoning 9) | thread_id=01a0f419-9fd2-79e2-8248-91436f04e297

Why this exists

A single model doing everything has three recurring problems, and delegation solves each one:

Your context window is finite. Having Claude read forty files to answer one question spends context you need for the actual work. Delegating the investigation returns the answer instead of the forty files.

One model has one set of blind spots. A second opinion is worth most when it comes from a different model family — different training, different failure modes. Asking the same model twice mostly gets you the same answer twice.

Not every task deserves the same reasoning budget. Renaming a variable and diagnosing a race condition are not the same job. Here they are separate dials: the *model* sets raw capability, the *reasoning effort* sets how long it deliberates. Cheap work goes to a fast model; a hard problem gets the capable one thinking for as long as it needs.

The server runs on your machine and drives the Codex CLI you already have installed; it holds no credentials of its own. Prompts reach OpenAI through Codex, exactly as when you run codex yourself.

See How it compares for a versioned comparison with other Codex MCP servers.

Using it

Write a bounded delegation

A delegation gets expensive when repeated commands keep adding output to the context carried into later requests. Name the exact question, likely files, stopping condition and evidence the answer must contain; choose higher effort for ambiguity rather than by habit. [Writing a delegation](docs/DELEGATING.md) gives the measured cost model, ranked rules and weak-versus-strong examples using the real tool parameters. Background goes in context and a persona or extra rules in system_instructions, both layered on the built-in quality contract; see the tool reference.

Get a second opinion from a different model family

The value here is not a second run — it is a different set of blind spots.

Ask Codex to review src/server.ts for correctness problems, focusing on error paths. Use a high

reasoning effort and tell it to report each finding with the line and why it matters.

A delegated review like this found the terminate() defect in this repository's own runner: two code paths could each arm a timer while only one was ever cleared.

Investigate without spending your context

Forty files go into the delegation; one answer comes back. Codex runs its own searches and reads whatever it needs; your conversation receives the conclusion.

Have Codex trace how a reasoning effort travels from the MCP tool call down to the arguments

handed to the Codex CLI, and report just the call chain.

Run long work in the background while you keep going

Kick off a Codex run in the background that writes unit tests for src/jobs.ts, then keep helping

me with the API layer.

You get a job_id immediately. Ask for the status whenever you want, and read the result when it is done. Up to eight can run at once; CODEX_SUBAGENT_MAX_BACKGROUND_JOBS can lower that cap. A background request cancelled before its job is created starts nothing.

Buy deep reasoning for one hard problem

Raising the reasoning effort for the whole conversation is expensive. Raising it for one delegation is not.

This intermittent test failure has beaten me twice. Ask Codex to work out the root cause at

maximum reasoning effort, give it test/runner.test.ts and the CI log, and tell it not to change

anything — I want the diagnosis first.

Keep the thread going

Ask Codex to expand on its second finding.

Follow-ups reuse Codex's context, so they cost a fraction of the original. The server restates the same model, effort and directory on every follow-up because Codex itself does not keep them on resume.

Let it write, when you mean it

Have Codex apply its first two suggestions. Let it edit files, but keep it inside a git worktree

so my working tree stays clean.

use_worktree sends the run's edits to ~/.codex/worktrees/; results list the file changes Codex reported and where each landed, up to a thousand distinct entries, then report the omitted count, and a line names the worktree and the commit it was made from. Codex is told beforehand that uncommitted changes, untracked files and ignored files such as installed dependencies are not in it. The server does not clean worktrees up: they may hold unapplied work. The experimental feature is enabled only for that invocation; your Codex configuration is unchanged. A follow-up continues in the same worktree; when Codex's session file could not confirm where that was, the follow-up asks for working_dir rather than resume in your working tree. See Safety for the write boundary.

Whatever the sandbox, a delegation that writes reports the file changes Codex recorded. It is Codex's account, not a diff of the disk:

Files changed (2):

• [edit] src/codex/runner.ts
• [add] test/runner.test.ts

Safety

This server runs another program on your machine, so it is worth two minutes before you enable writes.

What protects you

Delegations are read-only by default. Writing requires an explicit sandbox: "workspace-write" or a user-set default. use_worktree sends edits to a managed git worktree instead of your checkout; the sandbox and add_dirs bound where it can write at all. Unsandboxed runs are unavailable unless you explicitly opt into that ceiling.

The confinement is the operating system's own sandbox: Seatbelt on macOS, bubblewrap on Linux and WSL2, and a native sandbox on Windows. The table was measured on macOS; SECURITY.md records the measurement details. Linux and Windows have not been measured here, and OpenAI's Windows documentation notes that sandboxed commands can fail to read some directories, so reads may be stricter there:

The server chooses the sandbox mode on every run; Codex's own sandbox_workspace_write settings, such as network access or extra writable roots, are not overridden and still apply under workspace-write. The table reflects Codex's defaults.

The sandbox confines the commands Codex runs in its shell. It does not confine MCP or plugin tools: those run as their own processes with your account's full permissions, network included, and under read-only a tool that declares itself read-only runs without approval (measured on codex-cli 0.159.2; ADR 16). So a delegation inherits no MCP server, plugin or app from your Codex setup unless you allow it in the server configuration, and every delegation result includes a line saying what the run was allowed.

There is no shell in the server's invocation path: the CLI is spawned with an argv array and the prompt is written to its stdin, never interpolated into a command string. Shell metacharacters in a prompt are inert.

What does not protect you

Reads are not confined. Codex can read anything your user account can, in every mode — your SSH keys, your cloud credentials. That was measured on macOS, and it is the safe assumption on every platform. Sandboxed network access is blocked so it cannot send them anywhere, but its report comes back to you, and that is a channel.

A prompt is untrusted input, and Codex acts on it. Content you did not write — an issue body, a web page, a log, a file from someone else's repository — can carry instructions. With workspace-write it can direct Codex to modify your repository; even read-only it can direct Codex to read something sensitive and put it in the answer. The sandbox bounds *where* Codex can write. It does not judge *what* it should write, or why it was asked. This is prompt injection, and it is the risk that matters here.

The result is not sanitised. What comes back is text from a model that just read your files. Treat it as data, not as instructions; review what a delegation did rather than assuming it did what you asked.

Reducing the risk

• Leave the built-in default alone. Read-only handles investigation, review and diagnosis, which is most delegation.
• If you never want writes, cap it: CODEX_SUBAGENT_MAX_SANDBOX=read-only. No conversation can argue past a ceiling. Register it outside the repository (Claude Code's default local scope, --scope user, or Claude Desktop's config), not in a project .mcp.json that a write-enabled delegation could edit. See Configuration.
• When you enable writes, add use_worktree so changes land somewhere you can inspect before they touch your branch.
• Allow MCP servers, plugins or apps in delegations only when a task needs them, and by name. An allowed one runs outside the sandbox, and with auto_approve its tools need no approval at all.
• Do not assemble delegation prompts from untrusted content when you intend to act on the answer.
• If this threat matters seriously to you, run Codex under an account or container with no access to your secrets. That solves it at the root instead of bounding it.

SECURITY.md has the full threat model, what a deny_read policy could add, and how to report a vulnerability.

Configuration

Everything is optional, and set through environment variables on the MCP server:

| `CODEX_SUBAGENT_DEFAULT_MO