codex-bridge-mcp

A two-way MCP bridge that lets Claude Code drive the Codex CLI, and lets Codex talk back.

• Claude writes a plan → Codex executes it, or adversarially reviews it against the real code.

• While working, Codex can ask Claude questions (and block until answered) or send progress / findings.

• Claude can answer, send corrections mid-run, or start follow-up turns in the same Codex session.

• Keep several named Codex sessions per project, e.g. a reviewer on high effort and an executor on a cheaper setting.

Claude Code ──MCP "codex"──▶ server.mjs ──spawns──▶ codex exec --json
     ▲                          │                       │
     │                   ~/.codex-bridge/jobs/<id>/     │ MCP "claude_bridge"
     └──── codex_wait ◀──────── mailbox ◀───────────────┘ (injected per job)

Requirements

• Node.js 18+

• Codex CLI, logged in (codex login). Tested with codex-cli 0.162.

• Claude Code

Related MCP server: claude-code-codex-agents

Install

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

Or from source:

git clone https://github.com/WeiqiZhou2002/codex-bridge-mcp.git
cd codex-bridge-mcp && npm install
claude mcp add codex -s user -- node "$PWD/server.mjs"

Then start a new Claude Code session. claude mcp list should show codex ✔ Connected.

Usage

Just ask Claude in plain language:

Start a Codex reviewer on xhigh and have it adversarially review plans/plan-v3.md.

Start a Codex executor on high to implement the plan; it should ask me if anything is unclear.

Tell the reviewer that finding #2 is wrong because the cache is per-request, and ask it to re-check.

Tools Claude gets (server codex)

Anywhere a job_id is expected you can pass the job's name instead; the newest job with that name wins. A job's model, effort and sandbox are fixed at start and reused by every follow-up turn.

Tools Codex gets (server claude_bridge, injected via -c per job)

Your normal ~/.codex/config.toml (default model, other MCP servers, etc.) still applies.

How it works

Each job gets a directory under ~/.codex-bridge/jobs/<id>/ (override with CODEX_BRIDGE_HOME):

• events.jsonl: Codex → Claude. Questions, messages, a digest parsed from codex exec --json, turn results.

• answers/<qid>.json: Claude → Codex answers to ask_claude.

• inbox.jsonl: Claude → Codex unsolicited messages.

Follow-up turns use codex exec resume <session_id>. Job metadata persists on disk, so a later Claude session can keep talking to the same Codex session. Turns that were running when the previous Claude session exited are marked resumable.

Caveats

• execute mode lets Codex write inside the working directory. danger-full-access is only used if you ask for it explicitly.

• In Codex's workspace-write sandbox, Codex usually cannot write to .git, so let Claude (or you) do the commits.

• Codex's --json event format is not a stable API. If a Codex upgrade changes it, the activity digest may get thinner, but final answers still come through.

• Two jobs in the same folder do not share context. Claude relays between them.

Development

npm test

The tests drive the server through a real MCP client against a fake codex binary (test/fake-codex.mjs), so they are fast and don't spend tokens. Set CODEX_BIN to point the bridge at a different Codex executable.

License

MIT