codexmcp/docs/README_EN.md at main · GuDaStudio/codexmcp

Seamlessly Bridge Claude Code and Codex

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

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.

Please ensure you have successfully installed the uv tool:

Windows Run the following command in PowerShell:

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

Linux/macOS Download and install using curl/wget:

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

wget -qO- https://astral.sh/uv/install.sh | sh # Using wget

Note: We strongly recommend Windows users run this project in WSL!

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

1.4 Optionally allow Claude Code to automatically interact with Codex by adding mcp__codex__codex to the allow list in ~/.claude/settings.json

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
  - image (List[Path] | null): Attach one or more image files to the initial prompt, defaults to None
  - model (string | null): Specify the model to use, defaults to None (uses user's default configuration)
  - yolo (boolean | null): Run all commands without approval (skip sandboxing), defaults to False
  - profile (string | null): Configuration profile name to load from `~/.codex/config.toml`, defaults to None (uses user's default configuration)

  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
`image`	`List[Path] \| None`	❌	`None`	Attach image files to initial prompt
`model`	`str \| None`	❌	`None`	Specify model to use (defaults to user configuration)
`yolo`	`bool \| None`	❌	`False`	Run all commands without approval (skip sandboxing)
`profile`	`str \| None`	❌	`None`	Configuration profile name from `~/.codex/config.toml`

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

I. Introduction

II. Quick Start

0. Prerequisites

1. Installation Steps

2. Configure Claude Code Prompts (Optional)

III. Tool Documentation

IV. FAQ

🤝 Contributing

Development Environment Setup

Commit Guidelines

📄 License

Support us with a 🌟~

FilesExpand file tree

README_EN.md

Latest commit

History

README_EN.md

File metadata and controls

I. Introduction

II. Quick Start

0. Prerequisites

1. Installation Steps

2. Configure Claude Code Prompts (Optional)

III. Tool Documentation

IV. FAQ

🤝 Contributing

Development Environment Setup

Commit Guidelines

📄 License

Support us with a 🌟~