CLAUDE.md

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

Repository Type

This is an MCP (Model Context Protocol) server that wraps OpenAI's Codex CLI, exposing it as tools to Claude Code and other MCP clients.

Development Commands

# Build TypeScript to dist/
npm run build

# Development mode (runs src/index.ts directly with tsx)
npm run dev

# Run tests
npm test                # Run all tests
npm run test:watch      # Watch mode
npm run test:coverage   # With coverage report

# Run a single test file
npx jest src/__tests__/context-building.test.ts

# Linting and formatting
npm run lint          # ESLint
npm run lint:fix      # Auto-fix lint issues
npm run format        # Prettier
make lint             # Run both lint and format

Architecture

Core Flow

MCP Client (Claude Code)
    → StdioTransport
    → CodexMcpServer (server.ts)
    → ToolHandlers (handlers.ts)
    → executeCommand (command.ts)
    → Codex CLI

Key Files

File	Purpose
src/index.ts	Entry point, creates and starts CodexMcpServer
src/server.ts	MCP server setup, handles list_tools and call_tool requests
src/tools/definitions.ts	MCP tool schemas (input/output) and annotations
src/tools/handlers.ts	Tool execution logic (codex, review, websearch, etc.)
src/types.ts	Type definitions, Zod schemas, tool constants
src/session/storage.ts	In-memory session storage for conversation context
src/utils/command.ts	Command spawning with streaming support and Windows compatibility
src/errors.ts	Custom error classes (ValidationError, ToolExecutionError)

MCP Tools

• codex: Execute Codex CLI with session support, model selection, reasoning effort, sandbox mode, full-auto, and working directory options
• review: Code review for uncommitted changes, branches, or commits
• websearch: Web search using Codex CLI with --search flag
• listSessions: View active conversation sessions
• ping: Test server connection
• help: Get Codex CLI help

Session Management

Sessions enable multi-turn conversations with Codex:

1. First request with sessionId: Creates session, runs normal codex exec, extracts conversation/session ID from stderr
2. Subsequent requests with same sessionId: Uses codex exec resume <conversation-id> (native Codex resume)
3. Fallback: If no conversation ID exists, manually builds enhanced prompt from conversation history

Important: When resuming sessions, sandbox, fullAuto, and workingDirectory parameters are NOT applied (Codex CLI limitation).

Streaming Progress

Tools support streaming progress via MCP notifications/progress:

// In server.ts - progress context is created from request._meta?.progressToken
const context = createProgressContext();

// In handlers - send progress updates
await context.sendProgress('Processing...', 1, 10);

Structured Output (Codex 0.87+)

When Codex emits threadId, it's returned in:

• content[0]._meta - For Claude Code compatibility
• structuredContent - For other MCP clients (enabled via STRUCTURED_CONTENT_ENABLED env var)

Important Implementation Details

Command Execution

• Stderr handling: Codex CLI writes most output to stderr, not stdout. Both are captured and merged.
• Exit codes: Commands that produce output are treated as success even if exit code is non-zero.
• Buffer truncation: Output truncated at 10MB to prevent memory exhaustion.
• Windows compatibility: Arguments are escaped for cmd.exe (% → %%, " → "").

Codex Command Structure

Commands are built differently based on mode:

Exec mode (new conversations):

codex exec --model X --sandbox Y [-c config=value] --skip-git-repo-check "prompt"

Resume mode (existing conversations):

codex exec --skip-git-repo-check -c model="X" -c model_reasoning_effort="Y" resume <conversation-id> "prompt"

Note: Config flags (-c) must come BEFORE the subcommand (exec or resume).

Environment Variables

• CODEX_DEFAULT_MODEL: Default model for codex/review tools (default: gpt-5.3-codex)
• CODEX_MCP_CALLBACK_URI: Static MCP callback URI passed to Codex (override via tool arg)
• STRUCTURED_CONTENT_ENABLED: Enable structuredContent in responses (default: false)

TypeScript Configuration

• Target: ES2022, Module: ESNext
• Output: dist/ directory
• Strict mode enabled
• All imports must include .js extension (ESM)