codex-router-mcp

An MCP server that puts guardrails around delegating work to OpenAI Codex.

Codex already ships its own MCP server (codex mcp-server), and it exposes two tools: codex and codex-reply. If all you want is "run a Codex session from another agent", use that — it is first-party and costs you nothing to maintain.

This project exists for what happens around the delegation:

• Quota is checked before a thread is started, normalized by window duration, and an exhausted account returns a structured handoff instead of a failure.

• Risky work runs in a dedicated git worktree, so a bad turn cannot touch your working tree.

• Every turn is bracketed by checkpoints, so you can roll one back.

• Reviews run read-only, in both directions, optionally with a second model.

• Failed writes are reported as failed, never as changes.

Claude Code  ──MCP──▶  codex-router-mcp  ──JSON-RPC──▶  codex app-server

One persistent codex app-server child process serves every thread, so the second delegation does not pay the startup cost again. Concurrent delegations each get their own thread and never cross results.

Requirements

• Node 20+

• The codex CLI on PATH, logged in (codex login) or configured with an API key

Related MCP server: nokto-agent-orchestrator MCP server

Install

claude mcp add codex-router -s user -- npx -y codex-router-mcp

Or from a clone:

npm install && npm run build
claude mcp add codex-router -s user -- node "/absolute/path/to/dist/index.js"

-s user makes it available in every project. A relative path only resolves from the directory the client was started in, so use an absolute one.

Give the model a policy

Installing the tools gives the model the ability to delegate. It still needs a policy for when. Put something like this in your global agent instructions — without it the model sees ten tools and no guidance:

You are the tech lead. Codex is an external subagent; you decide what to delegate.

• Delegate work that is self-contained, mechanical and narrowly scoped — migrations, refactors that follow a pattern, filling in tests, boilerplate. Do it yourself when it needs architectural judgement, context from the conversation, or is small enough that delegating costs more than it saves.

• Check codex_get_limits before anything large. Pick the model and reasoning effort from codex_get_models to match the difficulty; never guess ids.

• Use isolation: "worktree" for large, risky or experimental work, or when there is uncommitted work that must not be lost.

• status: "running" means Codex is still working. Poll codex_task_status; never delegate the same task twice.

• Always review what Codex produced — changed files, diff, then the code — and check it stayed inside scope. Send corrections through codex_continue.

• On quota_exhausted, read remainingWork and finish the task yourself. Never wait for a quota reset and never retry in a loop.

• If failedFileChanges is present, those files were not written. Do not review them.

CLAUDE.md is the full version this repository runs on (in Polish).

Tools

Quota

Limits are normalized by window duration, not by slot name:

primary is not assumed to be the 5h window — the API is free to put the weekly window there. Per window you get usedPercent, remainingPercent, resetsAt (ISO + epoch), resetsInMinutes and rateLimitReached, plus tightest (the window that actually gates the next turn) and a verdict: ok, low (delegate, with a warning attached) or exhausted.

The handoff

When quota runs out — at preflight or mid-turn — you get this instead of a failure:

{
  "status": "quota_exhausted",
  "taskId": "codex-20260829173437-001",
  "originalTask": "...",
  "threadId": "01a04e96-7474-79a1-a173-8c3cc2919eeb",
  "changedFiles": ["src/a.ts (update)"],
  "summary": "Codex ran out of quota mid-task. ...",
  "remainingWork": "Unfinished plan steps reported by Codex: ...",
  "limits": { "windows": [ ... ] },
  "nextStep": "Do NOT wait for the quota to reset ... finish it yourself."
}

The router never retries and never waits for a reset. Partial work is reported so the calling agent can continue from where Codex stopped.

A non-quota failure returns status: "failed" instead — the two are kept distinct so a compile error is not mistaken for a billing problem.

Isolation: git worktrees

isolation: "worktree" creates a linked worktree on a dedicated branch (agent-router/<taskId> unless you pass branch) and points Codex at it. Your working tree is never touched, whatever the turn does.

Worktrees are created under ~/.agent-router/worktrees/ — outside the repository, so they never appear in git status. If workingDirectory was a subdirectory of the repo, Codex is placed in the matching subdirectory.

For an isolated task, changedFiles and diff are computed against the commit the branch started from, so they show the cumulative result across every turn.

Integration is deliberately manual:

codex_worktree({ taskId, action: "commit" })   # work lands on the task branch
git merge agent-router/<taskId>                # you run this, not the router
codex_worktree({ taskId, action: "remove" })   # clean up

The router never writes to your branch.

Checkpoints

Inside a git repository, the working tree is snapshotted before and after every turn, capturing tracked and untracked files while respecting .gitignore.

The snapshot is built through a throwaway GIT_INDEX_FILE, so it never disturbs what you have staged. git stash create is the obvious primitive but it silently omits untracked files — exactly what a delegated agent tends to produce.

codex_checkpoints(taskId)
codex_restore({ taskId, checkpointId: "cp-1" })

codex_restore rewrites file contents with git restore --worktree, leaving the index alone. Files created after the checkpoint are reported as leftoverFiles and only deleted when removeUntracked: true is passed. Every restore first captures the current state and returns it as safetyCheckpoint, so a restore is itself undoable.

Checkpoints are dangling commits, not refs. They survive normal use and git's default garbage collection, but an explicit git gc --prune=now discards them.

Review

codex_review uses Codex's native review/start with inline delivery and a read-only sandbox — the reviewer cannot edit what it reviews.

• Pass workingDirectory to have Codex review your uncommitted work.

• Pass taskId (optionally with a different model) to have Codex review a previous Codex task. The reviewer is given the original task and its scope, so it also flags work that went out of bounds.

target selects what to review: uncommittedChanges (default), baseBranch, commit, or custom.

Honest failure reporting

Codex can finish a turn cleanly while every write it attempted was rejected — a misconfigured sandbox does exactly that. In that case changedFiles stays empty, the rejected patches are listed under failedFileChanges, and a warning tells the caller not to review files that were never written.

Known issue: the Codex sandbox on Windows

AGENT_ROUTER_SANDBOX defaults to workspace-write. On Windows that sandbox needs a helper binary, codex-windows-sandbox-setup.exe, that some Codex installations do not ship. When it is missing every write is silently rejected.

Reproduce it without this server:

codex sandbox cmd /c "echo hi > test.txt"

A healthy install writes the file; a broken one prints orchestrator_helper_launch_failed: ... program not found. Note that windowsSandbox/readiness still reports ready, so it does not catch this.

Repair the Codex installation if you can. AGENT_ROUTER_SANDBOX=danger-full-access works around it but removes the sandbox entirely — pair it with isolation: "worktree" at minimum.

Configuration

All optional, set as environment variables on the MCP server entry.

A task that outlives waitSeconds returns status: "running" with a taskId to poll, so an MCP call never blocks forever.

Tests

npm test

143 assertions. The real MCP server is booted over stdio but pointed at test/fake-app-server.mjs instead of codex app-server, so the whole router — JSON-RPC client, notification wiring, quota policy, task store, git plumbing — is exercised without a Codex account and without spending quota. Git cases run against throwaway repositories. This is what CI runs on Linux, macOS and Windows.

npm run smoke

Read-only check against the real codex app-server: prints the live model catalogue and current limits. Starts no turn, so it spends no quota.

Stability and terms

This server talks to codex app-server, which the Codex CLI marks [experimental]. Its protocol has no public documentation or stability guarantee; the type definitions in src/protocol.ts mirror only the subset used here and were derived from codex app-server generate-ts. A Codex release can change it. Regenerate and re-check if something breaks:

codex app-server generate-ts --out ./generated-ts

On terms: this server does not fork Codex, does not touch authentication, and does not reimplement any OpenAI client. It spawns the official codex binary you installed and logged into yourself. OpenAI has stated that the Codex CLI is Apache-2.0 and that forking is permitted, but has not clarified whether third-party tools driving a ChatGPT-plan session are covered by the Terms of Use, and their docs recommend API keys for automation. If you are automating heavily, or building anything commercial on this, use an API key and take your own legal advice.

License

MIT — see LICENSE.