Skip to content

CLAUDE.md

Latest commit

 

History

History
279 lines (222 loc) · 10.7 KB

CLAUDE.md

File metadata and controls

279 lines (222 loc) · 10.7 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Codex Bridge is a lightweight MCP (Model Context Protocol) server that enables Claude Code to interact with OpenAI's Codex AI through the official CLI. The project follows extreme simplicity principles from Carmack and Torvalds - doing ONE thing well: bridging Claude to Codex CLI.

Key Characteristics:

  • Non-interactive execution with structured output formats (text, JSON, code)
  • Stateless architecture with no session management
  • Direct subprocess integration for optimal performance
  • Batch processing support for CI/CD workflows
  • Pipeline-friendly stdin support

Development Commands

Prerequisites

  • Codex CLI: Install from OpenAI (official CLI)
  • Authentication: Setup OpenAI API credentials
  • Verify: codex --version

Installation & Setup

Development Mode:

# Clone and install in development mode
git clone https://github.com/shelakh/codex-bridge.git
cd codex-bridge
pip install -e .

# Run directly from source
python -m src

Production Installation:

# Install from PyPI
pip install codex-bridge

# Or use uvx (recommended)
uvx codex-bridge

Claude Code Integration:

# Production installation (recommended)
claude mcp add codex-bridge -s user -- uvx codex-bridge

# Development mode (from local source)
claude mcp add codex-bridge -s user -- python -m src

Testing & Verification

# Test CLI availability
codex --version

# Test basic functionality
python -c "from src.mcp_server import execute_codex_prompt; print('MCP server loaded successfully')"

# Test package installation
python -c "import src; print(f'Codex Bridge v{src.__version__}')"

Build & Distribution

# Clean build
rm -rf dist/ build/ *.egg-info

# Build package
uvx --from build pyproject-build

# Verify build
pip install dist/*.whl
python -c "import src; print('Package works!')"

Architecture

Core Design Principles

  • CLI-First: Direct subprocess calls to codex command
  • Stateless: Each tool call is independent with no session state
  • Non-Interactive: Structured execution with JSON/text/code formats
  • Configurable Timeout: Default 90-second execution time (configurable via CODEX_TIMEOUT)
  • Git Repository Check: Configurable via CODEX_SKIP_GIT_CHECK for non-git directories
  • Fail-Fast: Clear error messages with simple error handling
  • Zero Dependencies: Only mcp>=1.0.0 and external Codex CLI

Key Components

src/mcp_server.py - Main server implementation

  • consult_codex(query, directory, format, timeout) - Non-interactive consultation
  • consult_codex_with_stdin(stdin_content, prompt, directory, format, timeout) - Pipeline consultation
  • consult_codex_batch(queries, directory, format) - Batch processing
  • _format_response() - Output formatting for text/JSON/code

Codex CLI Integration:

  • Uses the official OpenAI Codex CLI without model selection
  • Single unified interface for AI-powered code assistance

File Structure

codex-bridge/
├── src/
│   ├── __init__.py              # Package entry point and version
│   ├── __main__.py              # Module execution entry point  
│   └── mcp_server.py            # Main MCP server implementation
├── .github/                     # GitHub templates and workflows
├── pyproject.toml               # Python package configuration
├── README.md                    # Main documentation
├── CONTRIBUTING.md              # Development guidelines
├── SECURITY.md                  # Security policy
├── CHANGELOG.md                 # Release history
└── LICENSE                      # MIT license

MCP Tools Available

consult_codex

  • Purpose: Non-interactive Codex consultation with structured output
  • Parameters:
    • query (required): The prompt to send to Codex
    • directory (required): Working directory for the query
    • format (optional): Output format - "text", "json", or "code" (default: "text")
    • timeout (optional): Timeout in seconds (overrides env var)
  • Use Case: Direct code generation, analysis, structured responses
  • Example: Code completion, refactoring suggestions

consult_codex_with_stdin

  • Purpose: Pipeline-friendly consultation with stdin content
  • Parameters:
    • stdin_content (required): Content to pipe (file contents, diffs, logs)
    • prompt (required): The prompt to process the stdin content
    • directory (required): Working directory for the query
    • format (optional): Output format - "text", "json", or "code" (default: "text")
    • timeout (optional): Timeout in seconds (overrides env var)
  • Use Case: CI/CD workflows, processing file contents, diff analysis
  • Example: Code reviews, log analysis, file processing

consult_codex_batch

  • Purpose: Batch processing for multiple queries - CI/CD automation
  • Parameters:
    • queries (required): List of query dictionaries with 'query' and optional 'timeout'
    • directory (required): Working directory for all queries
    • format (optional): Output format - currently only "json" supported
  • Use Case: Bulk operations, automated testing, batch analysis
  • Example: Multiple code reviews, batch refactoring, automated QA

Error Handling & Troubleshooting

Common Error Patterns

  • "CLI not available": Codex CLI not installed or not in PATH
    • Solution: Install official Codex CLI from OpenAI
  • "Authentication required": Not authenticated with OpenAI
    • Solution: Setup OpenAI API credentials
  • "Timeout after X seconds": Query too complex or model overloaded
    • Solution: Increase timeout with CODEX_TIMEOUT environment variable
    • Alternative: Break into smaller parts or use batch processing
  • "Not inside a trusted directory": Git repository check failed
    • Solution: Set CODEX_SKIP_GIT_CHECK=true environment variable (use only in trusted directories)
  • "Directory does not exist": Invalid directory parameter
    • Solution: Use absolute paths or verify directory exists
  • "Invalid format": Unsupported format parameter
    • Solution: Use "text", "json", or "code" formats only

Debugging Steps

  1. Verify Codex CLI: codex --version
  2. Test Authentication: codex "Hello World"
  3. Check Package: python -c "import src; print('OK')"
  4. Test MCP Tools: Use simple queries first, then add complexity

Development Guidelines

Code Standards

  • Python 3.10+ Compatibility: Use modern Python features responsibly
  • Type Hints: Include type annotations for all functions
  • Error Handling: Explicit error messages with actionable solutions
  • Documentation: Keep CLAUDE.md, README.md, and code comments in sync

Testing Requirements

  • Manual Testing: Verify all three MCP tools work with various queries
  • Integration Testing: Test with Claude Code in development
  • Cross-Platform: Ensure compatibility across Python versions (3.10-3.12)
  • CI/CD Verification: All GitHub Actions must pass

Performance Characteristics

  • Startup Time: Near-instant MCP server startup
  • Memory Usage: Minimal memory footprint (~10MB)
  • Execution Time: Limited by configurable timeout (default: 60 seconds)
  • Scalability: Stateless design allows multiple concurrent requests

Package Information

Dependencies

  • Required: mcp>=1.0.0
  • External: Codex CLI (official OpenAI CLI)
  • Python: Compatible with Python 3.10+

Installation Details

  • Package Name: codex-bridge
  • PyPI: Available as pip install codex-bridge
  • Entry Point: codex-bridge = "src:main"
  • Module Execution: python -m src

Configuration

  • Timeout: Configurable via CODEX_TIMEOUT environment variable (default: 90 seconds)
  • Git Repository Check: Configurable via CODEX_SKIP_GIT_CHECK environment variable (default: enabled)
  • Working Directory: Configurable per request
  • File Encoding: UTF-8 with error handling

Environment Variables

Set environment variables to customize behavior:

# Example: 2-minute timeout configuration
claude mcp add codex-bridge -s user --env CODEX_TIMEOUT=120 -- uvx codex-bridge

# Example: Enable for non-git directories (use only in trusted environments)
claude mcp add codex-bridge -s user --env CODEX_SKIP_GIT_CHECK=true -- uvx codex-bridge

# Example: Both configurations
claude mcp add codex-bridge -s user --env CODEX_TIMEOUT=120 --env CODEX_SKIP_GIT_CHECK=true -- uvx codex-bridge

Valid Variables:

  • CODEX_TIMEOUT: Positive integers (seconds), default: 90
    • Recommended: 120-300 seconds timeout for complex queries
  • CODEX_SKIP_GIT_CHECK: Boolean-like values ("true", "1", "yes"), default: false
    • Security Warning: Only use in trusted directories you control
    • Use case: Working in directories that are not Git repositories

Security Considerations

Secure Practices

  • Input Validation: Basic validation for queries and parameters
  • Process Isolation: Subprocess execution for CLI calls
  • No Network Exposure: All network requests handled by Codex CLI
  • Minimal Attack Surface: Simple, stateless architecture

Best Practices

  • Keep Codex CLI updated to latest version
  • Use absolute paths for file operations
  • Validate directory permissions before operations
  • Monitor for unusual CLI behavior or errors

Release & Deployment

Version Management

  • Semantic Versioning: MAJOR.MINOR.PATCH format
  • Current Version: 1.0.0 (check src/__init__.py)
  • Release Tags: Git tags trigger automated PyPI publishing

Deployment Options

  1. PyPI + uvx (Recommended): uvx codex-bridge
  2. PyPI + pip: pip install codex-bridge
  3. Development: python -m src from source

CI/CD Pipeline

  • GitHub Actions: Automated testing on Python 3.10-3.12
  • PyPI Publishing: Triggered by version tags (v*.*)
  • Quality Gates: Build verification, import testing, package validation

Support & Community

Getting Help

Contributing

  • Guidelines: See CONTRIBUTING.md for detailed development setup
  • Code Style: Follow PEP 8, use type hints, include docstrings
  • Testing: Manual testing required, automated CI verification
  • Community: Respectful, constructive feedback welcome

This CLAUDE.md file serves as the authoritative development guide for the Codex Bridge project. Keep it updated as the project evolves, ensuring consistency with README.md, CONTRIBUTING.md, and actual implementation.