codex-bridge

Give Claude Code a Codex sparring partner.

codex-bridge is an MCP server that lets Claude Code ask GPT Codex for adversarial planning, code review, debugging, research, and risk triage without leaving your project workflow.

The npm package is @ndcorder/codex-bridge. The installed CLI binary and MCP server key are both codex-bridge.

What It Does

• codex_plan: get an implementation plan with trade-offs and stop-ship checks before writing code.
• codex_review: ask Codex for critical code review, with evidence mode on by default.
• codex_ask: brainstorm, sanity-check assumptions, or compare approaches.
• codex_risk_radar: score a diff and choose the right collaboration depth.
• codex_research: run multi-turn research and write durable research artifacts.
• codex_debug: run structured root-cause analysis for hard bugs.
• codex_stats, codex_sessions, codex_reset: inspect and manage bridge sessions.

Requirements

• Node.js 20 or newer is recommended. CI runs on Node 20 and 22.
• The Codex CLI must be installed, authenticated, and available as codex on PATH.
• An MCP-capable client such as Claude Code.

Check the Codex CLI before configuring the bridge:

codex --version

Quick Start

From the project where you want Claude Code to use Codex:

npx -y @ndcorder/codex-bridge init

This command:

• creates or updates .mcp.json with a codex-bridge stdio server entry
• preserves existing MCP servers
• appends Codex Bridge guidance to CLAUDE.md if it is not already present

Restart Claude Code after running the init command.

Manual MCP Configuration

If you prefer to edit MCP config yourself, add this server entry:

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

First Workflows

Ask Codex to plan before a risky change:

Use codex_plan to review this approach before implementation:
<describe the feature, constraints, and files involved>

Ask for evidence-based review after changes:

Use codex_review with include_diff=true and evidence_mode=true.
Focus on security, data loss, and API regressions.

Use risk radar when deciding how much review a diff needs:

Use codex_risk_radar on the current diff and recommend whether to ask,
review, or plan then review.

See docs/USAGE.md for more workflows.

Configuration

Environment variables:

• CODEX_BRIDGE_MODEL or CODEX_MODEL: default model override. Default: gpt-5.3-codex.
• CODEX_BRIDGE_RETRIES: transient retry count. Default: 1.
• CODEX_BRIDGE_RETRY_BACKOFF_MS: retry backoff base in milliseconds. Default: 500.
• CODEX_BRIDGE_MAX_SESSIONS: max in-memory sessions before oldest-session eviction. Default: 200.
• CODEX_BRIDGE_SESSION_TTL_MS: session inactivity TTL in milliseconds. Default: 86400000.

Common per-request runtime options:

• working_dir: project directory for Codex file access and implicit session key.
• timeout: timeout in milliseconds, max 600000.
• session_id: explicit context isolation key.
• model: per-request Codex model override.
• retries: per-request retry count, max 10.
• retry_backoff_ms: per-request retry backoff base, max 60000.

Full tool schemas are in docs/TOOLS.md.

Documentation

• docs/INSTALL.md: installation, MCP setup, and verification.
• docs/USAGE.md: practical workflows and examples.
• docs/TOOLS.md: complete MCP tool reference.
• docs/TROUBLESHOOTING.md: common setup and runtime failures.
• docs/ARCHITECTURE.md: maintainer architecture notes.
• CONTRIBUTING.md: development workflow.
• RELEASE.md: release checklist.
• SECURITY.md: vulnerability reporting.
• CHANGELOG.md: release history.

Local Development

npm install
npm run build
npm test

Run the full verification suite:

npm run verify

The full suite includes unit tests, the MCP stdio smoke test, and the bake-off black-box suite.

Release Commands

• npm run release:bump: bump patch version in package.json and 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 and run npm pack --dry-run.
• npm run release:prepare: run verify, pack check, and release notes generation.

Publish scoped packages publicly with:

npm publish --access public

Package Contents

The npm package intentionally ships only runtime output and documentation:

• dist/src
• README.md
• CHANGELOG.md
• docs/*.md

Generated research artifacts are written to the consuming project's .codex-bridge/ directory when codex_research receives working_dir.