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

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"]
    }
  }
}

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