Codexmcp Claude Codex Collaboration

CodexMCP: Claude Code & Codex Collaboration

Skill by 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)

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Linux/macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

Install CodexMCP

1. Remove official Codex MCP (if installed):

claude mcp remove codex

2. Install CodexMCP:

claude mcp add codex -s user --transport stdio -- uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp

3. Verify installation:

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:

## 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

Return Value

Success:

{
  "success": true,
  "SESSION_ID": "550e8400-e29b-41d4-a716-446655440000",
  "agent_messages": "Codex response text...",
  "all_messages": []  // Only when return_all_messages=True
}

Failure:

{
  "success": false,
  "error": "Error message"
}

Usage Patterns

Pattern 1: Single-shot Code Review

# 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

# 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

# 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

# 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

# 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:

   {
       "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:

   {
       "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:

   {
       "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:

   {
       "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:

# 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

# ✅ 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:

# ✅ Use absolute paths
params = {
    "cd": "/home/user/projects/myapp",
    "PROMPT": "..."
}

# ✅ Or resolve relative paths first
import os
params = {
    "cd": os.path.abspath("./myapp"),
    "PROMPT": "..."
}

# ❌ Don't use relative paths directly
params = {
    "cd": "./myapp",  # May not resolve correctly
    "PROMPT": "..."
}

Git Repository Check Failing

Problem: Codex refuses to run outside Git repository

Solutions:

# Option 1: Initialize Git repo
# $ cd /path/to/project
# $ git init

# Option 2: Skip the check (not recommended for production)
params = {
    "PROMPT": "...",
    "cd": "/path/to/project",
    "skip_git_repo_check": True  # Bypass Git requirement
}

Sandbox Permission Errors

Problem: Codex cannot write files when needed

Solutions:

# For read-only analysis (safest, default)
params = {"sandbox": "read-only"}

# For workspace modifications
params = {"sandbox": "workspace-write"}

# For full access (use with caution)
params = {"sandbox": "danger-full-access"}

# Or skip sandbox entirely (not recommended)
params = {"yolo": True}

Model Configuration Issues

Problem: Using wrong model or hitting rate limits

Solutions:

# Use specific model
params = {
    "PROMPT": "...",
    "cd": "/project",
    "model": "claude-3-opus"  # Specify model
}

# Use custom profile from ~/.codex/config.toml
params = {
    "PROMPT": "...",
    "cd": "/project",
    "profile": "production"  # Load specific config
}

Debugging Reasoning Failures

Problem: Codex gives unexpected results

Solutions:

# Enable full message trace
params = {
    "PROMPT": "...",
    "cd": "/project",
    "return_all_messages": True  # See full reasoning chain
}

# Inspect the response
response = codex_tool(**params)
for msg in response.get("all_messages", []):
    print(f"{msg['role']}: {msg['content']}")

Advanced Configuration

Custom Codex Config Profile

Edit ~/.codex/config.toml:

[profiles.production]
model = "claude-3-opus"
max_tokens = 8192
temperature = 0.3

[profiles.experimental]
model = "claude-3-sonnet"
max_tokens = 16384
temperature = 0.7

Use in CodexMCP:

params = {
    "PROMPT": "...",
    "cd": "/project",
    "profile": "production"  # Load this profile
}

Environment Variables

CodexMCP respects standard Codex CLI environment variables:

# Set default model
export CODEX_MODEL="claude-3-opus"

# Set API key (if needed)
export ANTHROPIC_API_KEY="sk-ant-..."

# Custom config location
export CODEX_CONFIG_PATH="~/.config/codex/custom.toml"

Integration Examples

Example: Full Development Cycle

# Step 1: Claude analyzes requirements
# (Manual interaction with user)

# Step 2: Claude asks Codex for implementation plan
plan_response = codex_tool(
    PROMPT="Create implementation plan for user authentication with JWT tokens",
    cd="/path/to/project",
    sandbox="read-only"
)
session_id = plan_response["SESSION_ID"]

# Step 3: Claude asks for code prototype
prototype_response = codex_tool(
    PROMPT="Generate unified diff patch for JWT auth implementation",
    cd="/path/to/project",
    SESSION_ID=session_id,
    sandbox="read-only"
)

# Step 4: Claude refines and implements
# (Claude writes actual code based on prototype)

# Step 5: Claude asks Codex to review
review_response = codex_tool(
    PROMPT="Review the implemented JWT authentication for security issues",
    cd="/path/to/project",
    SESSION_ID=session_id,
    sandbox="read-only",
    return_all_messages=True
)

# Step 6: Claude addresses feedback and iterates

Best Practices

1. Always use sandbox="read-only" for Codex prototyping to prevent accidental changes
2. Track SESSION_ID for multi-round conversations
3. Use absolute paths for the cd parameter
4. Enable return_all_messages when debugging or tracing reasoning
5. Set up Git repositories before running Codex (or use skip_git_repo_check sparingly)
6. Use descriptive PROMPTs that clearly state the task and context
7. Leverage parallel sessions for independent tasks (different SESSION_IDs)
8. Review Codex outputs critically — treat them as suggestions, not final solutions

Resources

• GitHub Repository
• Official Homepage
• Codex CLI Documentation
• Claude Code Documentation
• MCP Protocol Specification