# 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
### Recommended Development Flow
```mermaid
graph LR
A[🔍 Analyze] --> B[🧠 Understand]
B --> C[📋 Plan]
C --> D[👁️ Review]
D --> E[⚡ Execute With Claude Code]
E --> F[✅ Validate]
```
1. **Analyze**: Use read-only mode to deeply understand your codebase
2. **Understand**: Let Codex explain complex relationships and patterns
3. **Plan**: Design comprehensive solutions and strategies
4. **Review**: Examine Codex's recommendations carefully
5. **Execute**: Enable write mode and apply changes thoughtfully using Claude Code
6. **Validate**: Test and verify the implemented changes
## 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 intelligent caching, security validation, and read-only safety defaults.
## Technical Architecture
```mermaid
graph TD
A[Claude Code] --> B[MCP Client]
B --> C{Claude-Codex Bridge}
C --> D[Delegation Decision Engine]
C --> E[Result Cache]
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. **Result Cache**: Intelligent caching system based on content hashes, avoiding duplicate executions
4. **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)
```bash
pip install claude-codex-bridge
```
#### From Source
1. **uv Package Manager** (if building from source): `curl -LsSf https://astral.sh/uv/install.sh | sh`
2. **Clone the project**
```bash
git clone https://github.com/xiaocang/claude-codex-bridge.git
cd claude-codex-bridge
```
3. **Install dependencies**
```bash
uv sync
```
Or with pip:
```bash
pip install -e .
```
4. **Configure environment variables** (optional)
```bash
# Copy environment variable template
cp .env.example .env
# Edit .env file, add API keys
vim .env
```
### Starting the Server
The server supports two operational modes:
#### 📋 Planning Mode (Default - Recommended)
Start in read-only mode for safe code analysis and planning:
**If installed from PyPI:**
```bash
claude-codex-bridge
```
**Or using Python module:**
```bash
python -m claude_codex_bridge
```
**If running from source:**
```bash
uv run python -m claude_codex_bridge
```
#### ⚡ Execution Mode (When Ready to Apply Changes)
Enable write operations when you're ready to implement Codex's recommendations:
**If installed from PyPI:**
```bash
claude-codex-bridge --allow-write
```
**Or using Python module:**
```bash
python -m claude_codex_bridge --allow-write
```
**If running from source:**
```bash
uv run python -m claude_codex_bridge --allow-write
```
#### Command-Line Options
- `--allow-write`: Enable file modification operations (default: read-only)
- `--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):**
```bash
# In your project directory - for safe analysis and planning
claude mcp add codex-planning --command "claude-codex-bridge" --scope project
```
**Execution Mode:**
```bash
# 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:**
```bash
# Copy the example configuration
cp .mcp.json.example .mcp.json
# Edit to match your setup
```
#### 2. Usage Examples
**Planning Phase (Read-Only):**
```
/mcp__codex-planning__codex_delegate "Analyze the authentication system for security vulnerabilities" --working_directory "/path/to/your/project" --task_complexity high
```
**Execution Phase (Write-Enabled):**
```
/mcp__codex-execution__codex_delegate "Implement the security fixes we planned earlier" --working_directory "/path/to/your/project" --task_complexity high
```
## 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
- `execution_mode` (optional): Approval strategy (default: on-failure)
- `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**:
```json
{
"task_description": "Analyze the user authentication system for security vulnerabilities and design improvement strategies",
"working_directory": "/Users/username/my-project",
"execution_mode": "on-failure",
"sandbox_mode": "read-only",
"output_format": "explanation",
"task_complexity": "medium"
}
```
**Execution Mode Example**:
```json
{
"task_description": "Implement the security improvements we planned for the authentication system",
"working_directory": "/Users/username/my-project",
"execution_mode": "on-failure",
"sandbox_mode": "workspace-write",
"output_format": "diff",
"task_complexity": "high"
}
```
### `cache_stats`
Get cache statistics and clean up expired entries.
### `clear_cache`
Clear all cache entries.
## Configuration Options
### Environment Variables
```bash
# Cache configuration
CACHE_TTL=3600 # Cache TTL in seconds
MAX_CACHE_SIZE=100 # Maximum cache entries
```
### Execution Mode Explanation
- **untrusted**: Only runs trusted commands, most secure
- **on-failure**: Requests approval on failure, recommended for most tasks
- **on-request**: Model decides when to request approval, suitable for complex tasks
- **never**: Never requests approval, suitable for simple automation tasks
### Sandbox Mode Explanation
- **read-only**: Read-only access, suitable for code analysis and explanation
- **workspace-write**: Writable workspace, suitable for most development tasks
- **danger-full-access**: Full access, use with caution
## Version History
### v0.1.2rc1
- 🆕 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](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 🚀
Raw data
{
"_id": null,
"home_page": null,
"name": "claude-codex-bridge",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "xiaocang <johnnywang1991@msn.com>",
"keywords": "ai, automation, claude, code-generation, codex, llm, mcp",
"author": null,
"author_email": "xiaocang <johnnywang1991@msn.com>",
"download_url": "https://files.pythonhosted.org/packages/a9/a7/738cb741942f2e64f1596cc49d2de553c582504c12f3420c6638aaa31aba/claude_codex_bridge-0.1.2.tar.gz",
"platform": null,
"description": "# Claude-Codex Bridge\n\nAn intelligent **MCP (Model Context Protocol) server** that leverages Codex's exceptional capabilities in **code analysis, architectural planning, and complex problem-solving**.\n\n## Screenshots\n\n\n\n## Philosophy: Think First, Execute Later\n\nClaude-Codex Bridge embraces a **planning-first approach** to software development. Codex's true strength lies not in blindly executing changes, but in:\n\n- \ud83e\udde0 **Deep Understanding**: Comprehending complex code relationships and patterns\n- \ud83d\udcca **Strategic Analysis**: Identifying optimization opportunities and architectural insights\n- \ud83c\udfaf **Thoughtful Planning**: Designing robust, well-considered solutions\n- \u2705 **Quality Assurance**: Reviewing code for best practices, security, and performance\n\n### Why Read-Only by Default?\n\n1. **Safety First**: Prevent accidental modifications during code exploration\n2. **Better Decisions**: Encourage thorough analysis before making changes\n3. **Learning Tool**: Understand the \"why\" behind recommendations, not just the \"what\"\n4. **Audit Trail**: Clear separation between planning and execution phases\n\n### Recommended Development Flow\n\n```mermaid\ngraph LR\n A[\ud83d\udd0d Analyze] --> B[\ud83e\udde0 Understand]\n B --> C[\ud83d\udccb Plan]\n C --> D[\ud83d\udc41\ufe0f Review]\n D --> E[\u26a1 Execute With Claude Code]\n E --> F[\u2705 Validate]\n```\n\n1. **Analyze**: Use read-only mode to deeply understand your codebase\n2. **Understand**: Let Codex explain complex relationships and patterns\n3. **Plan**: Design comprehensive solutions and strategies\n4. **Review**: Examine Codex's recommendations carefully\n5. **Execute**: Enable write mode and apply changes thoughtfully using Claude Code\n6. **Validate**: Test and verify the implemented changes\n\n## Project Overview\n\nClaude-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 intelligent caching, security validation, and read-only safety defaults.\n\n## Technical Architecture\n\n```mermaid\ngraph TD\n A[Claude Code] --> B[MCP Client]\n B --> C{Claude-Codex Bridge}\n\n C --> D[Delegation Decision Engine]\n C --> E[Result Cache]\n\n C --> G[Codex CLI]\n G --> H[Local Sandbox]\n\n C --> I[Output Parser]\n I --> B\n B --> A\n```\n\n### Component Overview\n\n1. **MCP Server**: High-performance server based on FastMCP, providing standardized tool interfaces\n2. **Delegation Decision Engine (DDE)**: Intelligently analyzes tasks and determines optimal execution strategies\n3. **Result Cache**: Intelligent caching system based on content hashes, avoiding duplicate executions\n4. **Output Parser**: Intelligently identifies and formats Codex output into structured data\n\n## Quick Start\n\n### Prerequisites\n\n1. **Python 3.11+**\n2. **OpenAI Codex CLI**: `npm install -g @openai/codex`\n\n### Installation\n\n#### From PyPI (Recommended)\n\n```bash\npip install claude-codex-bridge\n```\n\n#### From Source\n\n1. **uv Package Manager** (if building from source): `curl -LsSf https://astral.sh/uv/install.sh | sh`\n\n2. **Clone the project**\n ```bash\n git clone https://github.com/xiaocang/claude-codex-bridge.git\n cd claude-codex-bridge\n ```\n\n3. **Install dependencies**\n ```bash\n uv sync\n ```\n\n Or with pip:\n ```bash\n pip install -e .\n ```\n\n4. **Configure environment variables** (optional)\n ```bash\n # Copy environment variable template\n cp .env.example .env\n\n # Edit .env file, add API keys\n vim .env\n ```\n\n### Starting the Server\n\nThe server supports two operational modes:\n\n#### \ud83d\udccb Planning Mode (Default - Recommended)\nStart in read-only mode for safe code analysis and planning:\n\n**If installed from PyPI:**\n```bash\nclaude-codex-bridge\n```\n\n**Or using Python module:**\n```bash\npython -m claude_codex_bridge\n```\n\n**If running from source:**\n```bash\nuv run python -m claude_codex_bridge\n```\n\n#### \u26a1 Execution Mode (When Ready to Apply Changes)\nEnable write operations when you're ready to implement Codex's recommendations:\n\n**If installed from PyPI:**\n```bash\nclaude-codex-bridge --allow-write\n```\n\n**Or using Python module:**\n```bash\npython -m claude_codex_bridge --allow-write\n```\n\n**If running from source:**\n```bash\nuv run python -m claude_codex_bridge --allow-write\n```\n\n#### Command-Line Options\n- `--allow-write`: Enable file modification operations (default: read-only)\n- `--verbose`: Enable verbose output for debugging\n\n### Claude Code Integration\n\n#### 1. Configure MCP Server\nYou can configure separate servers for planning and execution modes:\n\n**Planning Mode (Default):**\n```bash\n# In your project directory - for safe analysis and planning\nclaude mcp add codex-planning --command \"claude-codex-bridge\" --scope project\n```\n\n**Execution Mode:**\n```bash\n# In your project directory - for applying changes\nclaude mcp add codex-execution --command \"claude-codex-bridge --allow-write\" --scope project\n```\n\n**Or use the example configuration file:**\n```bash\n# Copy the example configuration\ncp .mcp.json.example .mcp.json\n# Edit to match your setup\n```\n\n#### 2. Usage Examples\n\n**Planning Phase (Read-Only):**\n```\n/mcp__codex-planning__codex_delegate \"Analyze the authentication system for security vulnerabilities\" --working_directory \"/path/to/your/project\" --task_complexity high\n```\n\n**Execution Phase (Write-Enabled):**\n```\n/mcp__codex-execution__codex_delegate \"Implement the security fixes we planned earlier\" --working_directory \"/path/to/your/project\" --task_complexity high\n```\n\n## Main Tools\n\n### `codex_delegate`\n\nLeverage Codex's advanced analytical capabilities for code comprehension and strategic planning.\n\n**Codex Specializes In**:\n- \ud83d\udd0d Analyzing complex codebases and identifying improvement opportunities\n- \ud83c\udfd7\ufe0f Designing architectural solutions and refactoring strategies\n- \ud83d\udccb Planning implementation approaches for new features\n- \ud83e\uddea Generating comprehensive test strategies\n- \u26a1 Reviewing code for quality, security, and performance issues\n\n**Parameters**:\n- `task_description` (required): Describe what you want Codex to analyze or plan\n- `working_directory` (required): Project directory to analyze\n- `execution_mode` (optional): Approval strategy (default: on-failure)\n- `sandbox_mode` (optional): File access mode (forced to read-only unless --allow-write)\n- `output_format` (optional): How to format the analysis results (diff/full_file/explanation)\n- `task_complexity` (optional): Model reasoning effort (low/medium/high)\n- Codex CLI invocations time out after **1 hour** by default to support long-running analyses\n\n**Planning Mode Example**:\n```json\n{\n \"task_description\": \"Analyze the user authentication system for security vulnerabilities and design improvement strategies\",\n \"working_directory\": \"/Users/username/my-project\",\n \"execution_mode\": \"on-failure\",\n \"sandbox_mode\": \"read-only\",\n \"output_format\": \"explanation\",\n \"task_complexity\": \"medium\"\n}\n```\n\n**Execution Mode Example**:\n```json\n{\n \"task_description\": \"Implement the security improvements we planned for the authentication system\",\n \"working_directory\": \"/Users/username/my-project\",\n \"execution_mode\": \"on-failure\",\n \"sandbox_mode\": \"workspace-write\",\n \"output_format\": \"diff\",\n \"task_complexity\": \"high\"\n}\n```\n\n### `cache_stats`\n\nGet cache statistics and clean up expired entries.\n\n### `clear_cache`\n\nClear all cache entries.\n\n## Configuration Options\n\n### Environment Variables\n\n```bash\n# Cache configuration\nCACHE_TTL=3600 # Cache TTL in seconds\nMAX_CACHE_SIZE=100 # Maximum cache entries\n```\n\n### Execution Mode Explanation\n\n- **untrusted**: Only runs trusted commands, most secure\n- **on-failure**: Requests approval on failure, recommended for most tasks\n- **on-request**: Model decides when to request approval, suitable for complex tasks\n- **never**: Never requests approval, suitable for simple automation tasks\n\n### Sandbox Mode Explanation\n\n- **read-only**: Read-only access, suitable for code analysis and explanation\n- **workspace-write**: Writable workspace, suitable for most development tasks\n- **danger-full-access**: Full access, use with caution\n\n## Version History\n\n### v0.1.2rc1\n- \ud83c\udd95 Support specifying task complexity when invoking Codex\n- \u23f1\ufe0f Increase default timeout to 1 hour for Codex CLI operations\n\n### v0.1.1\n- \ud83d\udd04 Version update and maintenance release\n\n### v0.1.0\n- \u2705 Basic MCP server implementation\n- \u2705 Codex CLI integration\n- \u2705 Delegation Decision Engine\n- \u2705 Result caching system\n- \u2705 Security validation mechanism\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details\n\n## Support\n\nFor questions or suggestions, please create a GitHub Issue or contact the maintainers.\n\n---\n\n**Claude-Codex Bridge** - Making AI agent collaboration smarter \ud83d\ude80\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An intelligent MCP server for orchestrating task delegation between Claude and OpenAI Codex CLI",
"version": "0.1.2",
"project_urls": {
"Documentation": "https://github.com/xiaocang/claude-codex-bridge#readme",
"Homepage": "https://github.com/xiaocang/claude-codex-bridge",
"Issues": "https://github.com/xiaocang/claude-codex-bridge/issues",
"Repository": "https://github.com/xiaocang/claude-codex-bridge.git"
},
"split_keywords": [
"ai",
" automation",
" claude",
" code-generation",
" codex",
" llm",
" mcp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fa577804e17a0f323910818b62fb9abc2d567a3504e4b7bcc4716c735d426d8f",
"md5": "03f49bd7807b01806d164fdd54dad3d2",
"sha256": "71e3568a76b234adfa3740f721bd5414c12d666bb74dc2d28bd22472b3d295d5"
},
"downloads": -1,
"filename": "claude_codex_bridge-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "03f49bd7807b01806d164fdd54dad3d2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 19796,
"upload_time": "2025-08-21T14:29:33",
"upload_time_iso_8601": "2025-08-21T14:29:33.629029Z",
"url": "https://files.pythonhosted.org/packages/fa/57/7804e17a0f323910818b62fb9abc2d567a3504e4b7bcc4716c735d426d8f/claude_codex_bridge-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a9a7738cb741942f2e64f1596cc49d2de553c582504c12f3420c6638aaa31aba",
"md5": "48330ea773bd9a5e4b186462003cfa4e",
"sha256": "a17864ff8c16daa24a6f29bfb098dbf02b2a1aac0db0479f2d25dbebdf63924b"
},
"downloads": -1,
"filename": "claude_codex_bridge-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "48330ea773bd9a5e4b186462003cfa4e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 22698,
"upload_time": "2025-08-21T14:29:34",
"upload_time_iso_8601": "2025-08-21T14:29:34.748939Z",
"url": "https://files.pythonhosted.org/packages/a9/a7/738cb741942f2e64f1596cc49d2de553c582504c12f3420c6638aaa31aba/claude_codex_bridge-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-21 14:29:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xiaocang",
"github_project": "claude-codex-bridge#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "claude-codex-bridge"
}
JSON
