codexmcp-claude-codex-collaboration

# CodexMCP: Claude Code & Codex Collaboration > Skill by [ara.so](https://ara.so) — Codex Skills collection. CodexMCP is an MCP (Model Context Protocol) server that enables seamless collaboration between Claude Code and Codex. It bridges these two AI coding assistants, allowing Claude Code to handle architecture and planning while Codex handles implementation and debugging, with features like session persistence, parallel execution, and reasoning trace tracking. ## What It Does CodexMCP provides: - **Multi-round dialogue** between Claude Code and Codex with session management - **Parallel task execution** with isolated session IDs - **Reasoning trace tracking** for detailed debugging insights - **Enhanced error handling** and workspace safety controls - **Session persistence** across multiple interactions ## Installation ### Prerequisites Ensure you have: - Claude Code v2.0.56+ installed and configured - Codex CLI v0.61.0+ installed and configured - `uv` tool installed ([installation guide](https://docs.astral.sh/uv/getting-started/installation/)) **Windows (PowerShell):** ```powershell powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` **Linux/macOS:** ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` ### Install CodexMCP **1. Remove official Codex MCP (if installed):** ```bash claude mcp remove codex ``` **2. Install CodexMCP:** ```bash claude mcp add codex -s user --transport stdio -- uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp ``` **3. Verify installation:** ```bash claude mcp list ``` Expected output: ``` codex: uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp - ✓ Connected ``` **4. (Optional) Auto-approve MCP interactions:** Edit `~/.claude/settings.json` and add `mcp__codex__codex` to the allow list. ## Configuration ### Recommended Claude Code System Prompt Add to `~/.claude/CLAUDE.md` for optimal collaboration: ```markdown ## Core Instruction for CodeX MCP At any time, you must consider how to collaborate with Codex and leverage the MCP tools it provides. **Mandatory steps:** 1. After forming initial analysis of user requirements, inform Codex of the requirements and initial thoughts, and ask it to refine the analysis and implementation plan. 2. Before implementing specific coding tasks, **must request a code implementation prototype from Codex** (require Codex to only provide unified diff patch, strictly prohibit any real code modifications). After obtaining the prototype, you **must use it only as a logical reference, rewrite the code modification** to form enterprise-grade, highly readable, highly maintainable code before implementing the actual programming changes. 3. Whenever concrete coding behavior is completed, **must immediately use Codex to review code changes and corresponding requirement completion**. 4. Codex only provides reference; you **must have your own thinking and even question Codex's answers**. You and Codex must continuously debate to find the only path to truth. ## Codex Tool Invocation Specification ### Tool Parameters **Required:** - `PROMPT` (string): Task instruction for Codex - `cd` (Path): Working directory root path **Optional:** - `sandbox` (string): "read-only" (default), "workspace-write", "danger-full-access" - `SESSION_ID` (UUID | null): Continue previous session (default: None for new session) - `skip_git_repo_check` (boolean): Allow running outside Git repo (default: False) - `return_all_messages` (boolean): Return all messages including reasoning (default: False) - `image` (List[Path] | null): Attach image files to initial prompt - `model` (string | null): Specify model (default: user config) - `yolo` (boolean | null): Run all commands without approval (default: False) - `profile` (string | null): Config profile from ~/.codex/config.toml ### Best Practices - **Always save SESSION_ID** for multi-round dialogue - Use `sandbox="read-only"` for safe prototyping - Set `return_all_messages=True` for detailed debugging - Ensure `cd` points to an existing directory ``` ## API Reference ### The `codex` Tool CodexMCP provides a single MCP tool called `codex` that executes AI-assisted coding tasks. #### Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `PROMPT` | `str` | ✅ | - | Task instruction for Codex | | `cd` | `Path` | ✅ | - | Working directory root path | | `sandbox` | `Literal["read-only", "workspace-write", "danger-full-access"]` | ❌ | `"read-only"` | Sandbox policy | | `SESSION_ID` | `UUID \| None` | ❌ | `None` | Session ID for continuation | | `skip_git_repo_check` | `bool` | ❌ | `False` | Allow non-Git repos | | `return_all_messages` | `bool` | ❌ | `False` | Return full reasoning trace | | `image` | `List[Path] \| None` | ❌ | `None` | Attach images to prompt | | `model` | `str \| None` | ❌ | `None` | Specify model | | `yolo` | `bool \| None` | ❌ | `False` | Skip all approvals | | `profile` | `str \| None` | ❌ | `None` | Config profile name | #### Return Value **Success:** ```json { "success": true, "SESSION_ID": "550e8400-e29b-41d4-a716-446655440000", "agent_messages": "Codex response text...", "all_messages": [] // Only when return_all_messages=True } ``` **Failure:** ```json { "success": false, "error": "Error message" } ``` ## Usage Patterns ### Pattern 1: Single-shot Code Review ```python # In Claude Code, invoke Codex for code review # (This is conceptual - actual invocation happens through MCP) tool_params = { "PROMPT": "Review the authentication logic in src/auth.py for security issues", "cd": "/path/to/project", "sandbox": "read-only", "return_all_messages": True } # MCP tool call returns: { "success": True, "SESSION_ID": "abc-123", "agent_messages": "Found potential SQL injection in line 45..." } ``` ### Pattern 2: Multi-round Dialogue Session ```python # First request: Get implementation plan params_1 = { "PROMPT": "Analyze requirements for user authentication feature", "cd": "/path/to/project", "sandbox": "read-only" } # Returns: SESSION_ID = "session-xyz" # Second request: Continue the session params_2 = { "PROMPT": "Now generate a unified diff patch for the authentication module", "cd": "/path/to/project", "SESSION_ID": "session-xyz", # Continue previous conversation "sandbox": "read-only" } # Third request: Ask follow-up questions params_3 = { "PROMPT": "What about edge cases for token expiration?", "cd": "/path/to/project", "SESSION_ID": "session-xyz", "sandbox": "read-only" } ``` ### Pattern 3: Parallel Task Execution ```python # Task A: Bug investigation (isolated session) task_a = { "PROMPT": "Debug memory leak in data processor", "cd": "/path/to/project", "sandbox": "read-only" } # Returns: SESSION_ID_A = "task-a-123" # Task B: Feature prototyping (separate isolated session) task_b = { "PROMPT": "Create prototype for caching layer", "cd": "/path/to/project", "sandbox": "read-only" } # Returns: SESSION_ID_B = "task-b-456" # Both tasks run independently without context interference ``` ### Pattern 4: Detailed Reasoning Trace ```python # Enable full message history for debugging params = { "PROMPT": "Optimize database query performance in reports module", "cd": "/path/to/project", "sandbox": "read-only", "return_all_messages": True # Get full reasoning chain } # Returns: { "success": True, "SESSION_ID": "debug-session", "agent_messages": "Optimized query reduces execution time...", "all_messages": [ {"role": "reasoning", "content": "Analyzing query structure..."}, {"role": "tool_call", "content": "read_file reports/queries.py"}, {"role": "tool_result", "content": "...file contents..."}, {"role": "reasoning", "content": "Identified N+1 query pattern..."}, # ... full trace ] } ``` ### Pattern 5: Image-based Context ```python # Attach architecture diagram for context params = { "PROMPT": "Review this architecture and suggest improvements", "cd": "/path/to/project", "image": ["/path/to/architecture.png", "/path/to/flowchart.svg"], "sandbox": "read-only" } ``` ## Common Workflows ### Workflow 1: Claude Architecting + Codex Implementing 1. **Claude analyzes requirements** and creates high-level plan 2. **Claude invokes Codex** with architectural decisions: ```python { "PROMPT": "Based on this architecture, create implementation prototype for auth service", "cd": "/path/to/project", "sandbox": "read-only" } ``` 3. **Codex returns unified diff patch** (no actual changes) 4. **Claude reviews and refines** the code 5. **Claude implements** the final version 6. **Claude asks Codex to review** the implementation: ```python { "PROMPT": "Review the auth service implementation for security and best practices", "cd": "/path/to/project", "SESSION_ID": "previous-session-id", "sandbox": "read-only" } ``` ### Workflow 2: Bug Investigation 1. **Claude identifies bug symptoms** 2. **Claude delegates to Codex** for detailed investigation: ```python { "PROMPT": "Investigate null pointer exception in payment processor at line 234", "cd": "/path/to/project", "sandbox": "read-only", "return_all_messages": True # Get detailed trace } ``` 3. **Codex traces execution flow** and identifies root cause 4. **Claude formulates fix** based on Codex insights 5. **Claude asks Codex to validate** the fix ### Workflow 3: Code Refactoring 1. **Claude plans refactoring strategy** 2. **Claude requests Codex analysis**: ```python { "PROMPT": "Analyze technical debt in legacy payment module", "cd": "/path/to/project", "sandbox": "read-only" } ``` 3. **Codex identifies patterns** and suggests improvements 4. **Claude implements refactoring** in stages 5. **Codex reviews each stage** for consistency ## Troubleshooting ### Connection Issues **Problem:** `codex: ... - ✗ Not Connected` **Solutions:** ```bash # Check MCP configuration claude mcp list # Reinstall CodexMCP claude mcp remove codex claude mcp add codex -s user --transport stdio -- uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp # Restart Claude Code # (Close and reopen the application) ``` ### Session Not Persisting **Problem:** Session context is lost between calls **Solutions:** - Ensure `SESSION_ID` from previous response is passed to next call - Verify the returned `SESSION_ID` is a valid UUID - Check that the same `cd` path is used across session calls ```python # ✅ Correct: Save and reuse SESSION_ID response_1 = codex_tool(PROMPT="First task", cd="/project") session_id = response_1["SESSION_ID"] response_2 = codex_tool( PROMPT="Continue task", cd="/project", SESSION_ID=session_id # Reuse here ) # ❌ Wrong: Not passing SESSION_ID response_2 = codex_tool(PROMPT="Continue task", cd="/project") # New session! ``` ### Working Directory Errors **Problem:** Tool fails silently or returns "directory not found" **Solutions:** ```python # ✅ Use absolute paths params = {