Codex in Claude Code

Wiring OpenAI Codex into Claude Code as a second, independent frontier model — a parallel lane for self-contained work and, more importantly, a second opinion that reviews Claude's own output before it ships.

This repo documents exactly how that setup is configured and how it's used day to day. It's a reference, not a product: if you run Claude Code and also have a ChatGPT/Codex subscription, this is a working blueprint for making one model check the other.

---

The idea in one paragraph

Claude Code is the orchestrator — it holds the conversation, the tools (MCP), the repo context, and does the work. Codex runs as a separate worker authenticated with its own Codex subscription, reachable from inside a Claude Code session as a set of MCP tools. Claude uses it two ways: (1) offload self-contained, verifiable work so it runs in parallel without drawing down Claude's own limits, and (2) cross-check — hand Codex a finished artifact (a diff, a report, a computed number) and ask its top model to adversarially review it, or to blind-recompute a number from raw data without seeing Claude's answer. Claude always adjudicates. The whole point is to catch what the author is blind to.

┌──────────────────────────────────────────────────────────────┐
│  Claude Code  (orchestrator: conversation, MCP, repo, edits)  │
│                                                                │
│   produces an artifact ──────────────┐                         │
│                                       ▼                        │
│                          ┌─────────────────────────┐          │
│              MCP tools →  │  codex-fleet MCP server │          │
│         (codex_run, …)    └────────────┬────────────┘          │
│                                        ▼                        │
│                          ┌─────────────────────────┐          │
│                          │  CodexFleet dispatcher   │  routes  │
│                          │  (Python / HTTP client)  │  to box  │
│                          └────────────┬────────────┘          │
└───────────────────────────────────────┼───────────────────────┘
                                         ▼   HTTP (127.0.0.1:8787)
                          ┌─────────────────────────────┐
                          │  worker.py  (launchd service)│
                          │   wraps `codex exec`         │
                          │   own Codex subscription      │
                          └────────────┬────────────────┘
                                       ▼
                          structured findings / recomputed
                          number ──► Claude ADJUDICATES

---

Two ways Codex is used

Mode	What Claude hands over	What comes back
Parallel offload	A self-contained task on provided/public input (transform, extract, draft from a template)	The completed output, run off Claude's own rate limits
Cross-check (the important one)	A finished artifact + an adversarial reviewer prompt — or just raw data for a blind recompute	Structured findings (severity/category/location/problem/evidence/fix) or an independent number, which Claude reconciles and decides on

The cross-check is why this exists. A model reviewing its own work is a weak check; a different vendor's frontier model, run adversarially and told "you did not write this — find the defects," is a strong one. See docs/04-cross-check.md.

---

Repo map

Path	What
docs/01-architecture.md	The components (MCP server, dispatcher, worker) and how a request flows through them.
docs/02-setup.md	How Codex itself is installed and isolated, the launchd worker, the fleet config, and the MCP registration in Claude Code.
docs/03-usage.md	Calling Codex three ways: MCP tools in-session, the Python helper, the CLI. Models, tiers, and sandbox modes.
docs/04-cross-check.md	The feedback workflow: when it fires, the roles (Author / Cross-Critic / Adjudicator), blind recompute, and adjudication.
docs/05-guardrails.md	The hard "never route X to Y" rules that keep the setup safe and useful.
reviewer-spine.md	The exact adversarial-reviewer prompt handed to Codex on every cross-check.
examples/	A sanitized fleet config template and a runnable cross-check example.

---

Quickstart (if you're replicating this)

1. Install the Codex CLI and log it into an isolated home so it doesn't collide with anything else that uses ~/.codex — docs/02-setup.md.
2. Run the worker (worker.py) as a supervised service so it's always up.
3. Drop a codex-fleet.json pointing at the worker — copy examples/codex-fleet.example.json.
4. Register the codex-fleet MCP server in Claude Code's config.
5. In a session, ask Claude to cross-check something. It calls codex_run with the reviewer spine, reads the findings, and adjudicates.

---

Design principles

• Claude orchestrates; Codex reviews. Codex has no MCP, no session context, no auth, no skills. It receives a self-contained artifact and returns self-contained output. Never frame an offload as "Codex runs the build/migration" — it structurally can't.
• The reviewer is always the top model. A cheap model checking a frontier model adds noise, not perspective.
• Nothing sensitive leaves Claude. No secrets, tokens, PII, or identifying data is ever sent to the Codex worker. Cross-check inputs are scrubbed or public-only.
• Never a gate on an irreversible action. A context-blind second opinion is exactly that — a second opinion, never the greenlight on a destructive or production write.
• Respect "free." An inline Claude turn is already paid for. Offload only when parallelism or genuine independence beats it.