codexmcp/docs/README_EN.md

Seamlessly Bridge Claude Code and Codex

⭐ Star us on GitHub — Your support means the world! 🙏😊

English | 简体中文

---

I. Introduction

In today's AI-assisted programming landscape, Claude Code excels at architectural design and high-level thinking, while Codex demonstrates exceptional prowess in code generation and granular optimization. CodexMCP serves as the bridge between them, leveraging the MCP protocol to create powerful synergies:

• Claude Code: Requirements analysis, architectural planning, code refactoring
• Codex: Algorithm implementation, bug localization, code review
• CodexMCP: Session context management, multi-turn conversations, parallel task execution

Compared to the official Codex MCP implementation, CodexMCP introduces enterprise-grade features including session persistence, parallel execution, and reasoning trace tracking, enabling smarter and more efficient collaboration between AI programming assistants. Feature comparison at a glance:

Feature	Official Version	CodexMCP
Basic Codex Invocation	√	√
Multi-turn Conversations	×	√
Reasoning Detail Tracking	×	√
Parallel Task Support	×	√
Error Handling	×	√

---

II. Quick Start

0. Prerequisites

Please ensure you have successfully installed and configured both Claude Code and Codex.

• Claude Code Installation Guide
• Codex CLI Installation Guide

1. Installation Steps

1.1 Remove the official Codex MCP (if previously installed).

claude mcp remove codex

1.2 Install CodexMCP.

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

1.3 Verify the installation. Run in your terminal:

claude mcp list

Important

If you see the following output, installation was successful! codex: uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp - ✓ Connected

2. Configure Claude Code Prompts (Optional)

To optimize Claude Code's collaboration with Codex, we highly recommend adding the following to ~/.claude/CLAUDE.md

Expand to view prompt

## Core Instruction for CodeX MCP

At all times, you must consider how to collaborate with Codex during your current process, and how to invoke the Codex MCP tools as a safeguard for your objective and comprehensive analysis.
You **must execute** the following steps:
**1** After forming an initial analysis of the user's requirements, inform Codex of the user's needs and your preliminary approach, and ask it to refine the requirements analysis and implementation plan.
**2** Before implementing specific coding tasks, **you must request a code implementation prototype from Codex (require Codex to provide only a unified diff patch, strictly prohibiting any actual code modifications)**. After obtaining the code prototype, you **may only use it as a logical reference and must rewrite the code modifications**, creating enterprise-grade, highly readable, and highly maintainable code before executing the actual programming modification tasks.
**3** Whenever you complete actual coding actions, **you must immediately use Codex to review the code changes and the degree of requirement completion**.
**4** Codex can only provide references; you **must have your own thinking and even need to question Codex's answers**. "Reading books without thinking is worse than not reading" — your ultimate mission with Codex is to reach unified, comprehensive, and precise conclusions, so you must continuously debate to find the only path to truth.


## Codex Tool Invocation Specification

 1. Tool Overview

  Codex MCP provides a tool named `codex` for executing AI-assisted coding tasks. This tool **is invoked via the MCP protocol**, not via command line.

  2. Tool Parameters

  **Required** parameters:
  - PROMPT (string): Task instruction sent to Codex
  - cd (Path): Root path of the working directory for Codex execution

  Optional parameters:
  - sandbox (string): Sandbox policy, options:
    - "read-only" (default): Read-only mode, safest
    - "workspace-write": Allow writes within workspace
    - "danger-full-access": Full access permissions
  - SESSION_ID (UUID | null): For continuing previous sessions to enable multi-turn interactions with Codex, defaults to None (start new session)
  - skip_git_repo_check (boolean): Whether to allow running in non-Git repositories, defaults to False
  - return_all_messages (boolean): Whether to return all messages (including reasoning, tool calls, etc.), defaults to False

  Return value:
  {
    "success": true,
    "SESSION_ID": "uuid-string",
    "agent_messages": "agent's text response",
    "all_messages": []  // Only included when return_all_messages=True
  }
  Or on failure:
  {
    "success": false,
    "error": "error message"
  }

  3. Usage Methods

  Starting a new conversation:
  - Don't pass SESSION_ID parameter (or pass None)
  - Tool will return a new SESSION_ID for subsequent conversations

  Continuing a previous conversation:
  - Pass the previously returned SESSION_ID as parameter
  - Context from the same session will be preserved

  4. Invocation Standards

  **Must comply**:
  - Every time you call the Codex tool, you must save the returned SESSION_ID for subsequent conversations
  - The cd parameter must point to an existing directory, otherwise the tool will fail silently
  - Strictly prohibit Codex from making actual code modifications; use sandbox="read-only" to prevent accidents, and require Codex to provide only unified diff patches

  Recommended usage:
  - If detailed tracking of Codex's reasoning process and tool calls is needed, set return_all_messages=True
  - For precise location, debugging, rapid code prototyping, and similar tasks, prioritize using the Codex tool

  5. Notes

  - Session management: Always track SESSION_ID to avoid session confusion
  - Working directory: Ensure the cd parameter points to a correct and existing directory
  - Error handling: Check the success field in return values and handle possible errors

---

III. Tool Documentation

Click to view codex tool parameter documentation

Parameter	Type	Required	Default	Description
PROMPT	str	✅	-	Task instruction sent to Codex
cd	Path	✅	-	Codex working directory root path
sandbox	Literal	❌	"read-only"	Sandbox policy: read-only / workspace-write / danger-full-access
SESSION_ID	UUID | None	❌	None	Session ID (None starts new session)
skip_git_repo_check	bool	❌	False	Whether to allow running in non-Git repositories
return_all_messages	bool	❌	False	Whether to return complete reasoning information

Click to view codex tool return value structure

On success:

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

On failure:

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

---

IV. FAQ

Q1: Are there any additional fees?

CodexMCP itself is completely free and open source — no additional fees required!

Q2: Will parallel calls conflict?

No. Each call uses an independent SESSION_ID, ensuring complete isolation.

---

🤝 Contributing

We welcome all forms of contribution!

Development Environment Setup

# Clone the repository
git clone https://github.com/GuDaStudio/codexmcp.git
cd codexmcp

# Install dependencies
uv sync

Commit Guidelines

• Follow Conventional Commits
• Include test cases
• Update documentation

---

📄 License

This project is licensed under the MIT License. Copyright (c) 2025 guda.studio

---

Support us with a 🌟~