codex-bridge

MCP server that bridges Claude Code to GPT Codex for:

• codex_ask — adversarial brainstorming / tradeoff memos
• codex_review — critical code review with optional evidence mode
• codex_plan — implementation planning with stop-ship checks
• codex_risk_radar — diff risk scoring + recommended collaboration path
• codex_stats / codex_sessions / codex_reset — session telemetry and lifecycle controls

Quick start

Use from npm after publishing:

npx -y @ndcorder/codex-bridge init

That adds a codex-bridge MCP server entry to the current project's .mcp.json and appends Codex Bridge usage guidance to CLAUDE.md.

Prerequisite: install and authenticate the Codex CLI so codex --version works on your PATH.

For local development from this repository:

npm install
npm run build
npm start

The server runs over stdio (MCP transport).

Manual MCP config:

{
  "mcpServers": {
    "codex-bridge": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ndcorder/codex-bridge"]
    }
  }
}

Configuration

Environment variables:

• CODEX_BRIDGE_MODEL (or CODEX_MODEL) — default model override (gpt-5.3-codex)
• CODEX_BRIDGE_RETRIES — default transient retry count (default 1)
• CODEX_BRIDGE_RETRY_BACKOFF_MS — default retry backoff base in ms (default 500)
• CODEX_BRIDGE_MAX_SESSIONS — max in-memory sessions before LRU-style eviction (default 200)
• CODEX_BRIDGE_SESSION_TTL_MS — session inactivity TTL before auto-expiry (default 86400000, 24h)

Per-request runtime options (ask/review/plan):

• working_dir — project directory for Codex file access
• timeout — timeout in ms
• session_id — explicit context isolation key
• model — per-request model override
• retries — per-request retry override
• retry_backoff_ms — per-request retry backoff override

Scripts

Core

• npm run build — compile TypeScript
• npm start — start MCP server on stdio
• npm test — build + unit tests
• npm run test:bakeoff — build + bake-off black-box suite
• npm run verify — unit tests + bake-off suite

Benchmark

• npm run bench — run benchmark suite
• npm run bench:avg — run 3 benchmark iterations and average
• npm run bench:hf — benchmark with HuggingFace-imported samples
• npm run bench:report — summarize latest benchmark JSON into markdown

Examples:

npm run bench:report -- --file=benchmark/results/2026-03-09-codex-averaged-3runs.json
npm run bench:report -- --out=benchmark/results/LATEST-SUMMARY.md

Release helpers

• npm run release:bump — bump patch version in package.json + package-lock.json
• npm run release:bump:patch|minor|major — explicit semver bump
• npm run release:notes — generate .release/RELEASE_NOTES.md from CHANGELOG.md
• npm run release:pack-check — build + npm pack --dry-run
• npm run release:prepare — full verify + pack check + release notes generation

Release process checklist:

• RELEASE.md

Publishing

The package is published under the @ndcorder scope because npm rejected the unscoped codex-bridge name as too similar to an existing package. First publish:

npm login
npm run release:prepare
npm publish --access public

Tool reference

Detailed MCP tool schemas and parameters:

• docs/TOOLS.md

Changelog

• CHANGELOG.md

Bake-off notes API

benchmark/bakeoff contains a notes API + black-box test harness used for reliability/security bake-offs.

npm run test:bakeoff