claude-codex-bridge

Bidirectional MCP server bridge between Claude Code and OpenAI Codex CLI.

Let Claude and Codex work as partners — each can ask the other for help, review code, explain logic, and plan performance improvements.

┌──────────────┐         MCP          ┌──────────────┐
│              │ ◄──────────────────► │              │
│  Claude Code │    claude-codex      │  Codex CLI   │
│              │ ◄───── bridge ─────► │              │
└──────────────┘                      └──────────────┘

Prerequisites

• Claude Code CLI — installed and authenticated
• Codex CLI — installed and authenticated
• Node.js >= 18

Quick Start

Set up everything with a single command:

npx claude-codex-bridge setup

This registers MCP servers for both Claude Code and Codex, and installs the /codex skill and codex-teammate agent.

Setup

Automatic (recommended)

npx claude-codex-bridge setup              # Full setup: both directions + skill + agent
npx claude-codex-bridge setup claude       # Only Claude Code → Codex
npx claude-codex-bridge setup codex        # Only Codex → Claude
npx claude-codex-bridge setup --skip-extras  # MCP servers only, no skill/agent

Use --global or --local to control where the skill and agent are installed (defaults to interactive prompt).

Manual

Claude Code → Codex (let Claude call Codex)

Add to your Claude Code MCP config:

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

Or add to .mcp.json in your project:

{
  "mcpServers": {
    "codex": {
      "type": "stdio",
      "command": "npx",
      "args": ["claude-codex-bridge", "serve", "codex"]
    }
  }
}

Codex → Claude (let Codex call Claude)

Add to ~/.codex/config.toml:

[mcp_servers.claude]
command = "npx"
args = ["claude-codex-bridge", "serve", "claude"]
tool_timeout_sec = 600

Usage

Once set up, just talk to Claude Code or Codex naturally. The bridge tools are picked up automatically.

In Claude Code — ask Codex for help

> Ask Codex to review my recent changes

> Get Codex's opinion on whether this approach is correct: [paste plan]

> Have Codex explain how the parser in src/lib/codex-output-parser.ts works

> Ask Codex to analyze performance bottlenecks in the exec runner

> Ask Codex to implement error handling for the retry logic

In Codex — ask Claude for help

> Ask Claude to review the changes in HEAD~3..HEAD

> Have Claude explain the architecture of this project

> Ask Claude to critique my plan for adding caching

Using the /codex slash command (Claude Code)

Install the skill to get the /codex shortcut in Claude Code:

npx claude-codex-bridge install skill claude --global    # or --local

Then use it:

/codex review my recent changes
/codex explain src/lib/exec-runner.ts
/codex is my approach to caching correct?
/codex optimize the output parser for memory usage

Using the /claude slash command (Codex)

Install the skill to get the /claude shortcut in Codex:

npx claude-codex-bridge install skill codex --global    # or --local

Then use it:

/claude review my recent changes
/claude explain the architecture of this project
/claude critique my plan for adding caching

Spawning Codex as a teammate

For parallel work, spawn Codex as a subagent from Claude Code:

> Spawn a codex-teammate to review src/lib/exec-runner.ts while we keep working

Tools

ccb-codex — Claude calls Codex

Tool	Description
codex_query	Ask Codex a question or give it a task
codex_review_code	Ask Codex to review code changes
codex_review_plan	Ask Codex to critique an implementation plan
codex_explain_code	Ask Codex to explain code / logic / architecture
codex_plan_perf	Ask Codex to plan performance improvements
codex_implement	Ask Codex to write or modify code

ccb-claude — Codex calls Claude

Tool	Description
claude_query	Ask Claude a question or give it a task
claude_review_code	Ask Claude to review code changes
claude_review_plan	Ask Claude to critique an implementation plan
claude_explain_code	Ask Claude to explain code / logic / architecture
claude_plan_perf	Ask Claude to plan performance improvements
claude_implement	Ask Claude to write or modify code

Codex Teammate Agent

You can spawn Codex as a Claude Code teammate — a subagent that automatically uses the bridge tools to give you a second opinion, review code, or work on tasks in parallel.

Install the Agent

npx claude-codex-bridge install agent --global    # or --local

Usage

Once installed, spawn the teammate from Claude Code using the Task tool:

# Code review
Task(subagent_type: "codex-teammate", prompt: "Review src/lib/exec-runner.ts for bugs and performance issues")

# Explain unfamiliar code
Task(subagent_type: "codex-teammate", prompt: "Explain the architecture of the MCP server in codex-server.ts")

# Critique a plan
Task(subagent_type: "codex-teammate", prompt: "Critique this plan: [your plan here]")

# Performance analysis
Task(subagent_type: "codex-teammate", prompt: "Analyze performance bottlenecks in the output parser")

# General question
Task(subagent_type: "codex-teammate", prompt: "What's the best approach for adding retry logic to the bridge?")

The agent automatically picks the right Codex tool (codex_review_code, codex_explain_code, codex_plan_perf, etc.) based on your request.

Configuration

Variable	Description	Default
BRIDGE_TIMEOUT_MS	Subprocess timeout in milliseconds	600000 (10 min)
BRIDGE_MAX_RETRIES	Auto-retries on transient errors (rate limits, 5xx, network)	2
BRIDGE_DEBUG	Enable debug logging to stderr	—
BRIDGE_DEPTH	Current recursion depth (set automatically)	0

Anti-Recursion Guard

The bridge automatically prevents infinite loops. If Claude calls Codex which tries to call Claude again, the second call is blocked (BRIDGE_DEPTH >= 2).

Development

git clone https://github.com/Dunqing/claude-codex-bridge.git
cd claude-codex-bridge
pnpm install

pnpm build         # Compile to dist/
pnpm test          # Run tests
pnpm lint          # Lint and type check

# Dev mode (no build needed)
pnpm dev:codex-server
pnpm dev:claude-server

License

MIT