Claude-Codex Bridge

An intelligent MCP (Model Context Protocol) server that leverages Codex's exceptional capabilities in code analysis, architectural planning, and complex problem-solving.

Screenshots

Philosophy: Think First, Execute Later

Claude-Codex Bridge embraces a planning-first approach to software development. Codex's true strength lies not in blindly executing changes, but in:

• 🧠 Deep Understanding: Comprehending complex code relationships and patterns
• 📊 Strategic Analysis: Identifying optimization opportunities and architectural insights
• 🎯 Thoughtful Planning: Designing robust, well-considered solutions
• ✅ Quality Assurance: Reviewing code for best practices, security, and performance

Why Read-Only by Default?

1. Safety First: Prevent accidental modifications during code exploration
2. Better Decisions: Encourage thorough analysis before making changes
3. Learning Tool: Understand the "why" behind recommendations, not just the "what"
4. Audit Trail: Clear separation between planning and execution phases

Project Overview

Claude-Codex Bridge is an Intelligent Analysis Engine that orchestrates task delegation between Claude Code and locally running OpenAI Codex CLI. Rather than a simple code generator, it's a sophisticated planning and analysis system with security validation and read-only safety defaults.

Technical Architecture

graph TD
    A[Claude Code] --> B[MCP Client]
    B --> C{Claude-Codex Bridge}

    C --> D[Delegation Decision Engine]

    C --> G[Codex CLI]
    G --> H[Local Sandbox]

    C --> I[Output Parser]
    I --> B
    B --> A

Component Overview

1. MCP Server: High-performance server based on FastMCP, providing standardized tool interfaces
2. Delegation Decision Engine (DDE): Intelligently analyzes tasks and determines optimal execution strategies
3. Output Parser: Intelligently identifies and formats Codex output into structured data

Quick Start

Prerequisites

1. Python 3.11+
2. OpenAI Codex CLI: npm install -g @openai/codex

Installation

From PyPI (Recommended)

pip install claude-codex-bridge

Starting the Server

The server supports two operational modes:

📋 Planning Mode (Default - Recommended)

Start in read-only mode for safe code analysis and planning:

Using Python module:

python -m claude_codex_bridge

⚡ Execution Mode (When Ready to Apply Changes)

Enable write operations when you're ready to implement Codex's recommendations:

Using Python module:

python -m claude_codex_bridge --allow-write

Command-Line Options

• --allow-write: Enable file modification operations (default: read-only)
• --legacy-cmd: Use legacy Codex CLI backend (codex exec). By default the bridge uses the Codex MCP backend.
• --verbose: Enable verbose output for debugging

Claude Code Integration

1. Configure MCP Server

You can configure separate servers for planning and execution modes:

Planning Mode (Default):

# In your project directory - for safe analysis and planning
claude mcp add codex-planning --command "claude-codex-bridge" --scope project

Execution Mode:

# In your project directory - for applying changes
claude mcp add codex-execution --command "claude-codex-bridge --allow-write" --scope project

Or use the example configuration file:

# Copy the example configuration
cp .mcp.json.example .mcp.json
# Edit to match your setup

Main Tools

codex_delegate

Leverage Codex's advanced analytical capabilities for code comprehension and strategic planning.

Codex Specializes In:

• 🔍 Analyzing complex codebases and identifying improvement opportunities
• 🏗️ Designing architectural solutions and refactoring strategies
• 📋 Planning implementation approaches for new features
• 🧪 Generating comprehensive test strategies
• ⚡ Reviewing code for quality, security, and performance issues

Parameters:

• task_description (required): Describe what you want Codex to analyze or plan
• working_directory (required): Project directory to analyze
• approval_policy (optional): Approval strategy (untrusted, on-failure [default], on-request, never)
• sandbox_mode (optional): File access mode (forced to read-only unless --allow-write)
• output_format (optional): How to format the analysis results (diff/full_file/explanation)
• task_complexity (optional): Model reasoning effort (low/medium/high)
• Codex CLI invocations time out after 1 hour by default to support long-running analyses

Planning Mode Example:

{
  "task_description": "Analyze the user authentication system for security vulnerabilities and design improvement strategies",
  "working_directory": "/Users/username/my-project",
  "approval_policy": "on-failure",
  "sandbox_mode": "read-only",
  "output_format": "explanation",
  "task_complexity": "medium"
}

Execution Mode Example:

{
  "task_description": "Implement the security improvements we planned for the authentication system",
  "working_directory": "/Users/username/my-project",
  "approval_policy": "on-failure",
  "sandbox_mode": "workspace-write",
  "output_format": "diff",
  "task_complexity": "high"
}

Version History

v0.1.4

• 🧩 API Rename: execution_mode → approval_policy with support for untrusted, on-failure (default), on-request, never
• 🧭 MCP Elicitation Passthrough: Relay interactive prompts upstream when possible; safe auto-decline fallback to prevent hangs
• 📝 MCP Logging: Add logging callback to capture Codex MCP logs for easier debugging
• ⏱️ Per-Request Timeouts: Pass read_timeout_seconds to tool calls to bound long-running operations
• 🧷 Read-Only Planning Improvements: Default to diff output when write is disabled; prompt includes actionable-diff guidance
• 🧪 E2E Tests: Add wrapper delimiter and MCP integration scripts
• 🧹 Cleanup: Remove unused MCP prompt templates

v0.1.3

• 🔄 Default Codex MCP Backend: Switch from CLI to MCP backend by default with --legacy-cmd fallback option
• 🛡️ Enhanced Security: Read-only sandbox mode as default, explicit --allow-write required for file modifications
• 🎯 Robust Output Extraction: New wrapper-style delimiter system with configurable start/end delimiters and strict mode support
• ⚙️ New CLI Options: Added --legacy-cmd flag for backward compatibility with CLI backend
• 🔧 Extended Tool Parameters: New final_output_start_delimiter, final_output_end_delimiter, final_output_strict, and request_id parameters for enhanced control
• 📊 Dynamic Tool Descriptions: Tool descriptions now adapt to current write permissions for precise guidance
• 🎨 Format-Specific Prompts: Automatic injection of format-specific prompt preambles for better model responses
• 🔒 Enforced Security Defaults: Operation mode notices when overriding to planning mode (read-only)
• 🛠️ Improved Content Detection: Better content-type detection applied after wrapper extraction
• 🧹 Architecture Cleanup: Complete removal of cache subsystem for simplified, more reliable operation
• ⚠️ Breaking Changes: Default sandbox mode changed from workspace-write to read-only, cache-related tools and response fields removed
• ❌ Removals: Cache subsystem, cache tests, cache environment variables, and cache-related MCP tools completely removed

v0.1.2

• 🆕 Support specifying task complexity when invoking Codex
• ⏱️ Increase default timeout to 1 hour for Codex CLI operations

v0.1.1

• 🔄 Version update and maintenance release

v0.1.0

• ✅ Basic MCP server implementation
• ✅ Codex CLI integration
• ✅ Delegation Decision Engine
• ✅ Result caching system
• ✅ Security validation mechanism

License

MIT License - see LICENSE file for details

Support

For questions or suggestions, please create a GitHub Issue or contact the maintainers.

Claude-Codex Bridge - Making AI agent collaboration smarter 🚀