# Claude-Codex Bridge
An intelligent **MCP (Model Context Protocol) server** for orchestrating task delegation between Claude and OpenAI Codex CLI.
## Project Overview
Claude-Codex Bridge is an **Agentic Bridge** that intelligently delegates coding tasks from Claude Code to locally running OpenAI Codex CLI. Rather than a simple request forwarder, it's an intelligent orchestration system with decision-making capabilities, featuring result caching and security validation.
## Core Features
### 🚀 Intelligent Task Delegation
- **Automatic Task Routing**: Intelligently analyzes tasks and decides whether to delegate to Codex CLI
- **Working Directory Management**: Secure working directory validation and file access control
- **Execution Mode Control**: Supports multiple execution and sandbox modes for different security requirements
### 🧠 Intelligent Processing
- **Context Enhancement**: Intelligent context generation and file content management
- **Error Handling**: Comprehensive error handling and fallback mechanisms
### ⚡ Performance Optimization
- **Intelligent Caching**: File content hash-based result caching system
- **Concurrency Control**: Asynchronous execution and timeout management
- **Resource Management**: LRU cache strategy and automatic cleanup mechanisms
### 🛡️ Security Assurance
- **Path Validation**: Strict working directory validation to prevent path traversal attacks
- **Sandbox Isolation**: Supports multiple sandbox modes to restrict filesystem access
- **Permission Control**: Fine-grained execution permission management
## 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. **uv Package Manager**: `curl -LsSf https://astral.sh/uv/install.sh | sh`
3. **OpenAI Codex CLI**: `npm install -g @openai/codex`
### Installation
#### From PyPI (Recommended)
```bash
pip install claude-codex-bridge
```
#### From Source
1. **Clone the project**
```bash
git clone https://github.com/xiaocang/claude-codex-bridge.git
cd claude-codex-bridge
```
2. **Install dependencies**
```bash
uv sync
```
Or with pip:
```bash
pip install -e .
```
3. **Configure environment variables** (optional)
```bash
# Copy environment variable template
cp .env.example .env
# Edit .env file, add API keys
vim .env
```
4. **Start the server**
If installed from PyPI:
```bash
claude-codex-bridge
```
Or if running from source:
```bash
uv run python -m claude_codex_bridge
```
Or directly:
```bash
uv run src/claude_codex_bridge/bridge_server.py
```
### Claude Code Integration
1. **Configure MCP Server**
If installed from PyPI:
```bash
# In your project directory
claude mcp add codex-bridge --command "claude-codex-bridge" --scope project
```
Or if running from source:
```bash
# In your project directory
claude mcp add codex-bridge --command "python -m claude_codex_bridge" --scope project
```
2. **Use Tools**
```
/mcp__codex-bridge__codex_delegate "Refactor main.py file to use async/await syntax" --working_directory "/path/to/your/project"
```
## Main Tools
### `codex_delegate`
Core task delegation tool that delegates coding tasks to Codex CLI.
**Parameters**:
- `task_description` (required): Natural language description of the task
- `working_directory` (required): Absolute path to the project working directory
- `execution_mode` (optional): Execution mode (untrusted/on-failure/on-request/never)
- `sandbox_mode` (optional): Sandbox mode (read-only/workspace-write/danger-full-access)
- `output_format` (optional): Output format (diff/full_file/explanation)
**Example**:
```json
{
"task_description": "Add email validation method to User class",
"working_directory": "/Users/username/my-project",
"execution_mode": "on-failure",
"sandbox_mode": "workspace-write",
"output_format": "diff"
}
```
### `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
## Development and Testing
### Running Tests
```bash
# Run all tests
uv run python -m pytest tests/
# Run specific tests
uv run python -m pytest tests/test_engine.py
uv run python -m pytest tests/test_cache.py
```
### Development Mode
```bash
# Debug with MCP Inspector
uv run mcp dev src/claude_codex_bridge/bridge_server.py
# Or if installed
mcp dev claude-codex-bridge
```
### Code Quality
```bash
# Code formatting
uv run black src/ tests/
# Type checking
uv run mypy src/
# Code linting
uv run flake8 src/ tests/
```
## Project Structure
```
claude-codex-bridge/
├── src/
│ └── claude_codex_bridge/
│ ├── __init__.py # Package initialization
│ ├── __main__.py # Entry point
│ ├── bridge_server.py # Main MCP server
│ ├── engine.py # Delegation Decision Engine
│ └── cache.py # Result caching system
├── tests/
│ ├── test_engine.py # Engine unit tests
│ └── test_cache.py # Cache unit tests
├── .env # Environment configuration
├── .mcp.json # MCP client configuration example
├── pyproject.toml # Project configuration
└── README.md # Project documentation
```
## Best Practices
### Writing Task Descriptions
✅ **Good task descriptions**:
- "Add a validate_email method to the User class to validate email format"
- "Refactor all authentication-related functions in src/auth.py file to use async/await"
- "Add boundary condition and exception handling tests for the calculate_tax function"
❌ **Avoid these descriptions**:
- "Improve the code"
- "Fix all issues"
- "Add new features"
### Security Recommendations
1. Use absolute paths to specify working directory
2. Use `read-only` sandbox mode for production environments
3. Regularly clean cache and log files
4. Monitor system resource usage
## Troubleshooting
### Common Issues
**Q: Codex CLI not found**
```
A: Make sure it's installed: npm install -g @openai/codex
```
**Q: Working directory validation failed**
```
A: Check that the directory path is absolute and exists
```
**Q: Cache miss**
```
A: File content changes invalidate cache, this is normal behavior
```
## Performance Optimization Tips
1. **Enable caching**: Set appropriate TTL and cache size
2. **Reasonable timeouts**: Set timeout based on task complexity
3. **Regular cleanup**: Use `clear_cache` tool to clean unused cache
## Version History
### 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 <your-email@example.com>",
"keywords": "ai, automation, claude, code-generation, codex, llm, mcp",
"author": null,
"author_email": "xiaocang <your-email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/5c/7c/9d0b79c0e76f063714fb1bd4dcffb437abf8b4f4972400ff0013cade29ef/claude_codex_bridge-0.1.0.tar.gz",
"platform": null,
"description": "# Claude-Codex Bridge\n\nAn intelligent **MCP (Model Context Protocol) server** for orchestrating task delegation between Claude and OpenAI Codex CLI.\n\n## Project Overview\n\nClaude-Codex Bridge is an **Agentic Bridge** that intelligently delegates coding tasks from Claude Code to locally running OpenAI Codex CLI. Rather than a simple request forwarder, it's an intelligent orchestration system with decision-making capabilities, featuring result caching and security validation.\n\n## Core Features\n\n### \ud83d\ude80 Intelligent Task Delegation\n- **Automatic Task Routing**: Intelligently analyzes tasks and decides whether to delegate to Codex CLI\n- **Working Directory Management**: Secure working directory validation and file access control\n- **Execution Mode Control**: Supports multiple execution and sandbox modes for different security requirements\n\n### \ud83e\udde0 Intelligent Processing\n- **Context Enhancement**: Intelligent context generation and file content management\n- **Error Handling**: Comprehensive error handling and fallback mechanisms\n\n### \u26a1 Performance Optimization\n- **Intelligent Caching**: File content hash-based result caching system\n- **Concurrency Control**: Asynchronous execution and timeout management\n- **Resource Management**: LRU cache strategy and automatic cleanup mechanisms\n\n### \ud83d\udee1\ufe0f Security Assurance\n- **Path Validation**: Strict working directory validation to prevent path traversal attacks\n- **Sandbox Isolation**: Supports multiple sandbox modes to restrict filesystem access\n- **Permission Control**: Fine-grained execution permission management\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. **uv Package Manager**: `curl -LsSf https://astral.sh/uv/install.sh | sh`\n3. **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. **Clone the project**\n ```bash\n git clone https://github.com/xiaocang/claude-codex-bridge.git \n cd claude-codex-bridge\n ```\n\n2. **Install dependencies**\n ```bash\n uv sync\n ```\n\n Or with pip:\n ```bash\n pip install -e .\n ```\n\n3. **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\n4. **Start the server**\n \n If installed from PyPI:\n ```bash\n claude-codex-bridge\n ```\n \n Or if running from source:\n ```bash\n uv run python -m claude_codex_bridge\n ```\n \n Or directly:\n ```bash\n uv run src/claude_codex_bridge/bridge_server.py\n ```\n\n### Claude Code Integration\n\n1. **Configure MCP Server**\n \n If installed from PyPI:\n ```bash\n # In your project directory\n claude mcp add codex-bridge --command \"claude-codex-bridge\" --scope project\n ```\n \n Or if running from source:\n ```bash\n # In your project directory\n claude mcp add codex-bridge --command \"python -m claude_codex_bridge\" --scope project\n ```\n\n2. **Use Tools**\n ```\n /mcp__codex-bridge__codex_delegate \"Refactor main.py file to use async/await syntax\" --working_directory \"/path/to/your/project\"\n ```\n\n## Main Tools\n\n### `codex_delegate`\n\nCore task delegation tool that delegates coding tasks to Codex CLI.\n\n**Parameters**:\n- `task_description` (required): Natural language description of the task\n- `working_directory` (required): Absolute path to the project working directory\n- `execution_mode` (optional): Execution mode (untrusted/on-failure/on-request/never)\n- `sandbox_mode` (optional): Sandbox mode (read-only/workspace-write/danger-full-access)\n- `output_format` (optional): Output format (diff/full_file/explanation)\n\n**Example**:\n```json\n{\n \"task_description\": \"Add email validation method to User class\",\n \"working_directory\": \"/Users/username/my-project\",\n \"execution_mode\": \"on-failure\",\n \"sandbox_mode\": \"workspace-write\",\n \"output_format\": \"diff\"\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## Development and Testing\n\n### Running Tests\n\n```bash\n# Run all tests\nuv run python -m pytest tests/\n\n# Run specific tests\nuv run python -m pytest tests/test_engine.py\nuv run python -m pytest tests/test_cache.py\n```\n\n### Development Mode\n\n```bash\n# Debug with MCP Inspector\nuv run mcp dev src/claude_codex_bridge/bridge_server.py\n# Or if installed\nmcp dev claude-codex-bridge\n```\n\n### Code Quality\n\n```bash\n# Code formatting\nuv run black src/ tests/\n\n# Type checking\nuv run mypy src/\n\n# Code linting\nuv run flake8 src/ tests/\n```\n\n## Project Structure\n\n```\nclaude-codex-bridge/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 claude_codex_bridge/\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization\n\u2502 \u251c\u2500\u2500 __main__.py # Entry point\n\u2502 \u251c\u2500\u2500 bridge_server.py # Main MCP server\n\u2502 \u251c\u2500\u2500 engine.py # Delegation Decision Engine\n\u2502 \u2514\u2500\u2500 cache.py # Result caching system\n\u251c\u2500\u2500 tests/\n\u2502 \u251c\u2500\u2500 test_engine.py # Engine unit tests\n\u2502 \u2514\u2500\u2500 test_cache.py # Cache unit tests\n\u251c\u2500\u2500 .env # Environment configuration\n\u251c\u2500\u2500 .mcp.json # MCP client configuration example\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u2514\u2500\u2500 README.md # Project documentation\n```\n\n## Best Practices\n\n### Writing Task Descriptions\n\n\u2705 **Good task descriptions**:\n- \"Add a validate_email method to the User class to validate email format\"\n- \"Refactor all authentication-related functions in src/auth.py file to use async/await\"\n- \"Add boundary condition and exception handling tests for the calculate_tax function\"\n\n\u274c **Avoid these descriptions**:\n- \"Improve the code\"\n- \"Fix all issues\"\n- \"Add new features\"\n\n### Security Recommendations\n\n1. Use absolute paths to specify working directory\n2. Use `read-only` sandbox mode for production environments\n3. Regularly clean cache and log files\n4. Monitor system resource usage\n\n## Troubleshooting\n\n### Common Issues\n\n**Q: Codex CLI not found**\n```\nA: Make sure it's installed: npm install -g @openai/codex\n```\n\n**Q: Working directory validation failed**\n```\nA: Check that the directory path is absolute and exists\n```\n\n**Q: Cache miss**\n```\nA: File content changes invalidate cache, this is normal behavior\n```\n\n## Performance Optimization Tips\n\n1. **Enable caching**: Set appropriate TTL and cache size\n2. **Reasonable timeouts**: Set timeout based on task complexity\n3. **Regular cleanup**: Use `clear_cache` tool to clean unused cache\n\n## Version History\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.0",
"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": "fecaa2148edf40b85bb8a10c535c7726cf201888245ce7b72880f317f84d9926",
"md5": "630e0fba232a7c3f194172351517ff2f",
"sha256": "4d44bafed7ccb76361b263efdb7fefe887e3fb0bf9d89fe09c44828233e92e32"
},
"downloads": -1,
"filename": "claude_codex_bridge-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "630e0fba232a7c3f194172351517ff2f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 16318,
"upload_time": "2025-08-13T14:51:57",
"upload_time_iso_8601": "2025-08-13T14:51:57.288728Z",
"url": "https://files.pythonhosted.org/packages/fe/ca/a2148edf40b85bb8a10c535c7726cf201888245ce7b72880f317f84d9926/claude_codex_bridge-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5c7c9d0b79c0e76f063714fb1bd4dcffb437abf8b4f4972400ff0013cade29ef",
"md5": "e0b9d835b38126ab8099d8375547ebed",
"sha256": "3a26ce9092c7ccf162d50e47fa34c4cf9f6d6fdbe1f6c55a5007a37b56d6f986"
},
"downloads": -1,
"filename": "claude_codex_bridge-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "e0b9d835b38126ab8099d8375547ebed",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 16113,
"upload_time": "2025-08-13T14:51:59",
"upload_time_iso_8601": "2025-08-13T14:51:59.004591Z",
"url": "https://files.pythonhosted.org/packages/5c/7c/9d0b79c0e76f063714fb1bd4dcffb437abf8b4f4972400ff0013cade29ef/claude_codex_bridge-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-13 14:51:59",
"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
