Claude-Codex Review

An MCP (Model Context Protocol) server that orchestrates iterative code reviews between Claude and OpenAI Codex. This enables a two-AI review workflow where Claude creates plans/implementations and Codex provides critical review feedback.

Features

• Plan Review: Claude creates a plan → Codex reviews → iterate until approved
• Implementation Review: Claude implements → Codex reviews against plan → iterate until approved
• Session Persistence: Uses Codex CLI's native session resume for true conversation continuity
• Review History: Tracks all iterations with concerns, suggestions, and responses
• Configurable: Customize codebase conventions, timeouts, and iteration limits

Prerequisites

• Python 3.10+
• Codex CLI installed and authenticated
• Claude Code CLI (or any MCP-compatible client)

Codex Configuration

Ensure your ~/.codex/config.toml has the model configured:

model = "gpt-5.2-codex"
model_reasoning_effort = "high"

Installation

From PyPI (when published)

pip install claude-codex-review

From Source

git clone https://github.com/goharanwar/claude-codex-review.git
cd claude-codex-review
pip install -e .

Using uvx (recommended for MCP)

uvx claude-codex-review

Configuration

Environment Variables

Variable	Default	Description
CODEX_REVIEW_MAX_ITERATIONS	5	Maximum review iterations per session
CODEX_REVIEW_TIMEOUT	300	Timeout in seconds for Codex CLI calls
CODEX_REVIEW_SAVE_PATH	(none)	Directory to save finalized plans
CODEX_REVIEW_CODEBASE_CONTEXT	(none)	Custom codebase conventions for reviews

Claude Code Integration

Add to your ~/.claude.json:

{
  "mcpServers": {
    "claude-codex-review": {
      "command": "uvx",
      "args": ["claude-codex-review"],
      "env": {
        "CODEX_REVIEW_MAX_ITERATIONS": "5",
        "CODEX_REVIEW_TIMEOUT": "300",
        "CODEX_REVIEW_SAVE_PATH": "/path/to/save/plans",
        "CODEX_REVIEW_CODEBASE_CONTEXT": "- Python with PEP8\n- Use type hints\n- Prefer composition over inheritance"
      }
    }
  }
}

Or run from local source:

{
  "mcpServers": {
    "claude-codex-review": {
      "command": "python",
      "args": ["-m", "claude_codex_review.server"],
      "cwd": "/path/to/claude-codex-review/src",
      "env": {
        "CODEX_REVIEW_MAX_ITERATIONS": "5"
      }
    }
  }
}

Available Tools

start_plan_review

Start a Codex review session for a plan.

Parameters:

• plan (required): The plan content to review
• user_request: The user's original request
• qa_context: Q&A during planning
• context: Additional project context
• focus_areas: Specific areas to focus review on
• max_iterations: Override default max iterations

start_implementation_review

Start a Codex review session for implementation code.

Parameters:

• code (required): The implementation code
• original_plan (required): The plan being implemented
• user_request: The user's original request
• qa_context: Q&A context
• file_paths: List of file paths being reviewed
• max_iterations: Override default max iterations

continue_review

Continue an existing review session with Claude's response.

Parameters:

• session_id (required): The Codex session ID
• claude_response (required): Claude's response addressing feedback

get_review_status

Get current status of a review session.

get_review_summary

Get a markdown summary of the entire review conversation.

save_plan

Save finalized plan to configured path.

Parameters:

• plan_content (required): The plan content
• filename (required): Filename (without extension)
• session_id: Include review summary if provided

end_review_session

Clean up a review session.

Usage Example

User: "Create a plan for adding user authentication"

Claude: [Creates authentication plan]
Claude: [Calls start_plan_review with plan and context]

Codex Response:
- Status: CHANGES_REQUESTED
- Concerns: ["Missing password hashing details", "No session timeout specified"]

Claude: [Updates plan to address concerns]
Claude: [Calls continue_review with updates]

Codex Response:
- Status: APPROVED
- Summary: "All concerns addressed. Plan approved."

Claude: [Calls save_plan to persist the reviewed plan]

How It Works

1. Initial Review: Uses codex exec --output-schema for structured JSON response
2. Session Resume: Uses codex exec resume <SESSION_ID> for follow-ups (preserves context)
3. Response Parsing: Supports both JSON and STATUS: prefix formats
4. History Tracking: Records all iterations for review summary generation

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run server locally
python -m claude_codex_review.server

License

MIT License - see LICENSE for details.