From c676615bb3c8b3c9b9ac631c411140857110a25b Mon Sep 17 00:00:00 2001 From: GuDaStudio Date: Sat, 8 Nov 2025 14:29:47 +0800 Subject: [PATCH] =?UTF-8?q?v0.1=EF=BC=9A=E6=9B=B4=E6=96=B0README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 235 ++++++++++++++++++++--------------------- docs/README.md | 258 --------------------------------------------- docs/README_EN.md | 261 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 380 insertions(+), 374 deletions(-) delete mode 100644 docs/README.md create mode 100644 docs/README_EN.md diff --git a/README.md b/README.md index 716a4d1..b04ee94 100644 --- a/README.md +++ b/README.md @@ -1,155 +1,156 @@ -![CodexMCP](images/title.png) +![这是图片](./images/title.png) -
+
-**Seamlessly Integrate Claude Code with Codex** *- from [GuDaStudio](https://cc.guda.studio/)* +**让 Claude Code 与 Codex 无缝协作** -[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/) [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/) [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)[![Share](https://img.shields.io/badge/share-000000?logo=x&logoColor=white)](https://x.com/intent/tweet?text=CodexMCP：让%20Claude%20Code%20与%20Codex%20无缝协作%20https://github.com/GuDaStudio/codexmcp%20%23AI%20%23Coding%20%23MCP) [![Share](https://img.shields.io/badge/share-1877F2?logo=facebook&logoColor=white)](https://www.facebook.com/sharer/sharer.php?u=https://github.com/GuDaStudio/codexmcp) [![Share](https://img.shields.io/badge/share-FF4500?logo=reddit&logoColor=white)](https://www.reddit.com/submit?title=CodexMCP：让%20Claude%20Code%20与%20Codex%20无缝协作&url=https://github.com/GuDaStudio/codexmcp) [![Share](https://img.shields.io/badge/share-0088CC?logo=telegram&logoColor=white)](https://t.me/share/url?url=https://github.com/GuDaStudio/codexmcp&text=CodexMCP：让%20Claude%20Code%20与%20Codex%20无缝协作) -⭐ Star us on GitHub! Your support means the world to us! 🙏😊 -[![Share](https://img.shields.io/badge/share-000000?logo=x&logoColor=white)](https://x.com/intent/tweet?text=CodexMCP：Seamlessly%20integrate%20Claude%20Code%20with%20Codex%20https://github.com/GuDaStudio/codexmcp%20%23AI%20%23Coding%20%23MCP) [![Share](https://img.shields.io/badge/share-1877F2?logo=facebook&logoColor=white)](https://www.facebook.com/sharer/sharer.php?u=https://github.com/GuDaStudio/codexmcp) [![Share](https://img.shields.io/badge/share-FF4500?logo=reddit&logoColor=white)](https://www.reddit.com/submit?title=CodexMCP：Seamlessly%20integrate%20Claude%20Code%20with%20Codex&url=https://github.com/GuDaStudio/codexmcp) [![Share](https://img.shields.io/badge/share-0088CC?logo=telegram&logoColor=white)](https://t.me/share/url?url=https://github.com/GuDaStudio/codexmcp&text=CodexMCP：Seamlessly%20integrate%20Claude%20Code%20with%20Codex) +⭐ 在GitHub上给我们点星~您的支持对我们意义重大！ 🙏😊 -English | [简体中文](docs/README.md) +[English](./docs/README_EN.md) | 简体中文
--- -## 📖 Introduction +## 一、项目简介 -In the current AI-assisted programming ecosystem, **Claude Code** excels at architectural design and strategic thinking, while **Codex** shines in code generation and detail optimization. **CodexMCP** serves as a bridge between them, enabling their complementary strengths through the MCP protocol: +在当前 AI 辅助编程生态中，**Claude Code** 擅长架构设计与全局思考，而 **Codex** 在代码生成与细节优化上表现卓越。**CodexMCP** 作为两者之间的桥梁，通过 MCP 协议让它们优势互补： -- **Claude Code**: Handles requirements analysis, architectural planning, and code refactoring -- **Codex**: Handles algorithm implementation, bug locating, and code review -- **CodexMCP**: Manages session context, supports multi-turn dialogue and parallel tasks +- **Claude Code**：负责需求分析、架构规划、代码重构 +- **Codex**：负责算法实现、bug 定位、代码审查 +- **CodexMCP**：管理会话上下文，支持多轮对话与并行任务 -Compared to the official Codex MCP implementation, CodexMCP introduces enterprise-grade features such as **session persistence**, **parallel execution**, and **reasoning tracking**, making collaboration between AI programming assistants more intelligent and efficient. Here's a comparison between CodexMCP and the official Codex MCP: +相比官方 Codex MCP 实现，CodexMCP 引入了**会话持久化**、**并行执行**和**推理追踪**等企业级特性，让 AI 编程助手之间的协作更加智能高效。CodexMCP 与官方 Codex MCP 区别一览： -| Feature | Official Version | CodexMCP | -|---------|------------------|----------| -| Basic Codex Calls | ✓ | ✓ | -| Multi-turn Dialogue | × | ✓ | -| Reasoning Detail Tracking | × | ✓ | -| Parallel Task Support | × | ✓ | -| Error Handling | × | ✓ | +| 特性 | 官方版 | CodexMCP | +|------|--------|----------| +| 基本 Codex 调用 | √ | √ | +| 多轮对话 | × | √ | +| 推理详情追踪 | × | √ | +| 并行任务支持 | × | √ | +| 错误处理 | × | √ | --- -## ⚡ Quick Start +## 二、快速开始 -### 0. Prerequisites +### 0. 前置要求 -Please ensure you have successfully installed and configured both Claude Code and Codex programming tools. -- [Claude Code Installation Guide](https://docs.claude.com/docs/claude-code) -- [Codex CLI Installation Guide](https://developers.openai.com/codex/quickstart) +请确保您已成功**安装**和**配置**claude code与codex两个编程工具。 +- [Claude Code 安装指南](https://docs.claude.com/docs/claude-code) +- [Codex CLI 安装指南](https://developers.openai.com/codex/quickstart) -If you're struggling with subscription and configuration, we warmly welcome you to [contact us](https://cc.guda.studio). + -### 1. Installation Steps +### 1. 安装步骤 -1. Remove the official Codex MCP (if already installed). +**1.1** 移除官方 Codex MCP（如果已安装）。 ```bash claude mcp remove codex ``` -2. Install CodexMCP. +**1.2** 安装 CodexMCP。 ```bash claude mcp add codex --transport stdio -- uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp ``` -3. Verify installation. Run in your terminal: +**1.3** 验证安装。在 **终端** 中运行： ``` claude mcp list ``` > [!IMPORTANT] -> If you see the following description, the installation was successful! -> `codex: uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp - ✓ Connected` +> 如果看到如下描述，说明安装成功！ +> `codex: uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp - ✓ Connected` -### 2. Configure Claude Code Prompts (Optional) +### 2. 配置claude code提示词（可选） -To enable Claude Code to work better with Codex, we **strongly recommend adding the following content to `~/.claude/CLAUDE.md`** +为使claude code更好完成与codex的协同工作，我们**极力推荐您在 `~/.claude/CLAUDE.md`中添加以下内容**
-Expand to view prompt +展开查看prompt ``` -## codex Tool Usage Guidelines +## Core Instruction for CodeX MCP - 1. Tool Overview +在任何时刻，你必须思考当前过程可以如何与codex进行协作，如何调用Codex 为你提供的MCP工具作为你客观全面分析的保障。 +其中你**务必执行**以下几个步骤： +**1** 在你对用户需求形成初步分析后，将用户需求、初始思路告知codex，并要求其完善需求分析和实施计划。 +**2** 在实施具体编码任务前，**必须向codex索要代码实现原型（要求codex仅给出unified diff patch，严禁对代码做任何真实修改）**。在获取代码原型后，你**只能以此为逻辑参考，再次对代码修改进行重写**，形成企业生产级别、可读性极高、可维护性极高的代码后，才能实施具体编程修改任务。 +**3** 无论何时，只要完成切实编码行为后，**必须立即使用codex review代码改动和对应需求完成程度**。 +**4** codex只能给出参考，你**必须有自己的思考，甚至需要对codex的回答提出置疑**。尽信书则不如无书，你与codex的最终使命都是达成统一、全面、精准的意见，所以你们必须不断争辩已找到通向真理的唯一途径。 - The codex MCP provides a tool `codex` for executing AI-assisted coding tasks. This tool **is called via the MCP protocol**, no command line needed. - 2. Tool Parameters +## Codex Tool Invocation Specification - **Required** parameters: - - PROMPT (string): Task instruction sent to codex - - cd (Path): Root path of working directory for codex task execution + 1. 工具概述 - 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 interaction 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 + codex MCP 提供了一个工具 `codex`，用于执行 AI 辅助的编码任务。该工具**通过 MCP 协议调用**，无需使用命令行。 - Return value: + 2. 工具参数 + + **必选**参数： + - PROMPT (string): 发送给 codex 的任务指令 + - cd (Path): codex 执行任务的工作目录根路径 + + 可选参数： + - sandbox (string): 沙箱策略，可选值： + - "read-only" (默认): 只读模式，最安全 + - "workspace-write": 允许在工作区写入 + - "danger-full-access": 完全访问权限 + - SESSION_ID (UUID | null): 用于继续之前的会话以与codex进行多轮交互，默认为 None（开启新会话） + - skip_git_repo_check (boolean): 是否允许在非 Git 仓库中运行，默认 False + - return_all_messages (boolean): 是否返回所有消息（包括推理、工具调用等），默认 False + + 返回值： { "success": true, "SESSION_ID": "uuid-string", - "agent_messages": "agent's text response content", - "all_messages": [] // Only included when return_all_messages=True + "agent_messages": "agent回复的文本内容", + "all_messages": [] // 仅当 return_all_messages=True 时包含 } - Or on failure: + 或失败时： { "success": false, - "error": "error message" + "error": "错误信息" } - 3. Usage + 3. 使用方式 - Starting a new conversation: - - Don't pass SESSION_ID parameter (or pass None) - - Tool will return a new SESSION_ID for subsequent conversations + 开启新对话： + - 不传 SESSION_ID 参数（或传 None） + - 工具会返回新的 SESSION_ID 用于后续对话 - Continuing a previous conversation: - - Pass the previously returned SESSION_ID as a parameter - - Context from the same session will be preserved + 继续之前的对话： + - 将之前返回的 SESSION_ID 作为参数传入 + - 同一会话的上下文会被保留 - 4. Usage Guidelines + 4. 调用规范 - **Must follow**: - - 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 silently fail - - Strictly prohibit codex from making actual code modifications, use sandbox="read-only" to avoid accidents, and require codex to only provide unified diff patches + **必须遵守**： + - 每次调用 codex 工具时，必须保存返回的 SESSION_ID，以便后续继续对话 + - cd 参数必须指向存在的目录，否则工具会静默失败 + - 严禁codex对代码进行实际修改，使用 sandbox="read-only" 以避免意外，并要求codex仅给出unified diff patch即可 - Recommended usage: - - If you need to track codex's reasoning process and tool calls in detail, set return_all_messages=True - - For precise locating, debugging, rapid code prototyping, and other tasks, prioritize using the codex tool + 推荐用法： + - 如需详细追踪 codex 的推理过程和工具调用，设置 return_all_messages=True + - 对于精准定位、debug、代码原型快速编写等任务，优先使用 codex 工具 - 5. Typical Use Cases + 5. 注意事项 - codex excels at the following tasks, **must call codex** for these scenarios: - - 🎯 Precise Locating: Quickly locate issues in complex codebases - - 🐛 Debug Analysis: Analyze error messages and provide fix solutions - - ⚡ Code Prototyping: Rapidly generate code implementation prototypes or diff patches - - 🔍 Code Review: Comprehensive review of code changes - - 6. Notes - - - ⚠️ Session Management: Always track SESSION_ID to avoid session confusion - - ⚠️ Working Directory: Ensure cd parameter points to the correct and existing directory - - ⚠️ Error Handling: Check the success field in the return value to handle possible errors + - 会话管理：始终追踪 SESSION_ID，避免会话混乱 + - 工作目录：确保 cd 参数指向正确且存在的目录 + - 错误处理：检查返回值的 success 字段，处理可能的错误 ``` @@ -159,40 +160,40 @@ To enable Claude Code to work better with Codex, we **strongly recommend adding --- -## 🔧 Tool Documentation +## 三、工具说明
-Click to view codex tool parameter documentation +点击查看codex工具参数说明 -| 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 a 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 | +| 参数 | 类型 | 必填 | 默认值 | 说明 | +|------|------|------|--------|------| +| `PROMPT` | `str` | ✅ | - | 发送给 Codex 的任务指令 | +| `cd` | `Path` | ✅ | - | Codex 工作目录根路径 | +| `sandbox` | `Literal` | ❌ | `"read-only"` | 沙箱策略：`read-only` / `workspace-write` / `danger-full-access` | +| `SESSION_ID` | `UUID \| None` | ❌ | `None` | 会话 ID（None 则开启新会话） | +| `skip_git_repo_check` | `bool` | ❌ | `False` | 是否允许在非 Git 仓库运行 | +| `return_all_messages` | `bool` | ❌ | `False` | 是否返回完整推理信息 |
-Click to view codex tool return value structure +点击查看codex工具返回值结构 -**On success:** +**成功时：** ```json { "success": true, "SESSION_ID": "550e8400-e29b-41d4-a716-446655440000", - "agent_messages": "Codex's response content...", - "all_messages": [...] // Only included when return_all_messages=True + "agent_messages": "Codex 的回复内容...", + "all_messages": [...] // 仅当 return_all_messages=True 时包含 } ``` -**On failure:** +**失败时：** ```json { "success": false, - "error": "error message description" + "error": "错误信息描述" } ``` @@ -200,46 +201,46 @@ To enable Claude Code to work better with Codex, we **strongly recommend adding --- -## ❓ FAQ +## 四、FAQ
-Q1: Is there any additional cost? +Q1: 是否需要额外付费？ - CodexMCP itself is completely free and open source (MIT License), **no additional cost required!** + **CodexMCP 本身完全免费开源，无需任何额外付费！**
-Q2: Will parallel calls conflict? +Q2: 并行调用会冲突吗？ - No. Each call uses an independent `SESSION_ID`, completely isolated. +不会。每个调用使用独立的 `SESSION_ID`，完全隔离。
--- -## 🤝 Contributing +## 🤝 贡献指南
-We welcome all forms of contribution! +我们欢迎所有形式的贡献！ -### Development Environment Setup +### 开发环境配置 ```bash -# Clone the repository +# 克隆仓库 git clone https://github.com/GuDaStudio/codexmcp.git cd codexmcp -# Install dependencies +# 安装依赖 uv sync ``` -### Commit Guidelines +### 提交规范 -- Follow [Conventional Commits](https://www.conventionalcommits.org/) -- Submit test cases -- Update documentation +- 遵循 [Conventional Commits](https://www.conventionalcommits.org/) +- 提交测试用例 +- 更新文档
@@ -247,12 +248,14 @@ uv sync --- -## 📄 License +## 📄 许可证 -This project is licensed under the [MIT License](LICENSE). Copyright (c) 2025 [guda.studio](mailto:gudaclaude@gmail.com) +本项目采用 [MIT License](LICENSE) 开源协议。 +Copyright (c) 2025 [guda.studio](mailto:gudaclaude@gmail.com) --- - -**Support this project with a 🌟** +
+用 🌟 为本项目助力~ [![Star History Chart](https://api.star-history.com/svg?repos=GuDaStudio/codexmcp&type=date&legend=top-left)](https://www.star-history.com/#GuDaStudio/codexmcp&type=date&legend=top-left) +
\ No newline at end of file diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 6feeacb..0000000 --- a/docs/README.md +++ /dev/null @@ -1,258 +0,0 @@ -![这是图片](../images/title.png) - -
- - -**让 Claude Code 与 Codex 无缝协作** *- from [GuDaStudio](https://cc.guda.studio/)* - -[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/) [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io) - -⭐ 在GitHub上给我们点星~您的支持对我们意义重大！ 🙏😊 - -[![Share](https://img.shields.io/badge/share-000000?logo=x&logoColor=white)](https://x.com/intent/tweet?text=CodexMCP：让%20Claude%20Code%20与%20Codex%20无缝协作%20https://github.com/GuDaStudio/codexmcp%20%23AI%20%23Coding%20%23MCP) [![Share](https://img.shields.io/badge/share-1877F2?logo=facebook&logoColor=white)](https://www.facebook.com/sharer/sharer.php?u=https://github.com/GuDaStudio/codexmcp) [![Share](https://img.shields.io/badge/share-FF4500?logo=reddit&logoColor=white)](https://www.reddit.com/submit?title=CodexMCP：让%20Claude%20Code%20与%20Codex%20无缝协作&url=https://github.com/GuDaStudio/codexmcp) [![Share](https://img.shields.io/badge/share-0088CC?logo=telegram&logoColor=white)](https://t.me/share/url?url=https://github.com/GuDaStudio/codexmcp&text=CodexMCP：让%20Claude%20Code%20与%20Codex%20无缝协作) - -[English](README_EN.md) | 简体中文 - -
- ---- - -## 📖 项目简介 - -在当前 AI 辅助编程生态中，**Claude Code** 擅长架构设计与全局思考，而 **Codex** 在代码生成与细节优化上表现卓越。**CodexMCP** 作为两者之间的桥梁，通过 MCP 协议让它们优势互补： - -- **Claude Code**：负责需求分析、架构规划、代码重构 -- **Codex**：负责算法实现、bug 定位、代码审查 -- **CodexMCP**：管理会话上下文，支持多轮对话与并行任务 - -相比官方 Codex MCP 实现，CodexMCP 引入了**会话持久化**、**并行执行**和**推理追踪**等企业级特性，让 AI 编程助手之间的协作更加智能高效。CodexMCP 与官方 Codex MCP 区别一览： - - -| 特性 | 官方版 | CodexMCP | -|------|--------|----------| -| 基本 Codex 调用 | √ | √ | -| 多轮对话 | × | √ | -| 推理详情追踪 | × | √ | -| 并行任务支持 | × | √ | -| 错误处理 | × | √ | - - ---- - -## ⚡ 快速开始 - -### 零、 前置要求 - -请确保您已成功安装和配置claude code与codex两个编程工具。 -- [Claude Code 安装指南](https://docs.claude.com/docs/claude-code) -- [Codex CLI 安装指南](https://developers.openai.com/codex/quickstart) - -如果您正在为订阅和配置而忧愁，我们非常欢迎您[积极联系我们](https://cc.guda.studio)。 - -### 一、安装步骤 - -1. 移除官方 Codex MCP（如果已安装）。 - -```bash -claude mcp remove codex -``` - -2. 安装 CodexMCP。 - -```bash -claude mcp add codex --transport stdio -- uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp -``` - -3. 验证安装。在 命令行 中运行： - -``` -claude mcp list -``` - -> [!IMPORTANT] -> 如果看到如下描述，说明安装成功！ -> `codex: uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp - ✓ Connected` - -### 二、配置claude code提示词（可选） - -为使claude code更好完成与codex的协同工作，我们**极力推荐您在 `~/.claude/CLAUDE.md`中添加以下内容** - -
-展开查看prompt - - -``` -## codex 工具调用规范 - - 1. 工具概述 - - codex MCP 提供了一个工具 `codex`，用于执行 AI 辅助的编码任务。该工具**通过 MCP 协议调用**，无需使用命令行。 - - 2. 工具参数 - - **必选**参数： - - PROMPT (string): 发送给 codex 的任务指令 - - cd (Path): codex 执行任务的工作目录根路径 - - 可选参数： - - sandbox (string): 沙箱策略，可选值： - - "read-only" (默认): 只读模式，最安全 - - "workspace-write": 允许在工作区写入 - - "danger-full-access": 完全访问权限 - - SESSION_ID (UUID | null): 用于继续之前的会话以与codex进行多轮交互，默认为 None（开启新会话） - - skip_git_repo_check (boolean): 是否允许在非 Git 仓库中运行，默认 False - - return_all_messages (boolean): 是否返回所有消息（包括推理、工具调用等），默认 False - - 返回值： - { - "success": true, - "SESSION_ID": "uuid-string", - "agent_messages": "agent回复的文本内容", - "all_messages": [] // 仅当 return_all_messages=True 时包含 - } - 或失败时： - { - "success": false, - "error": "错误信息" - } - - 3. 使用方式 - - 开启新对话： - - 不传 SESSION_ID 参数（或传 None） - - 工具会返回新的 SESSION_ID 用于后续对话 - - 继续之前的对话： - - 将之前返回的 SESSION_ID 作为参数传入 - - 同一会话的上下文会被保留 - - 4. 调用规范 - - **必须遵守**： - - 每次调用 codex 工具时，必须保存返回的 SESSION_ID，以便后续继续对话 - - cd 参数必须指向存在的目录，否则工具会静默失败 - - 严禁codex对代码进行实际修改，使用 sandbox="read-only" 以避免意外，并要求codex仅给出unified diff patch即可 - - 推荐用法： - - 如需详细追踪 codex 的推理过程和工具调用，设置 return_all_messages=True - - 对于精准定位、debug、代码原型快速编写等任务，优先使用 codex 工具 - - 5. 典型使用场景 - - codex 极其擅长以下任务，涉及这些场景时**必须调用 codex**： - - 🎯 精准定位：在复杂代码库中快速定位问题所在 - - 🐛 Debug 分析：分析错误信息并提供修复方案 - - ⚡ 代码原型：快速生成代码实现的原型或 diff patch - - 🔍 代码审查：对代码改动进行全面 review - - 6. 注意事项 - - - ⚠️ 会话管理：始终追踪 SESSION_ID，避免会话混乱 - - ⚠️ 工作目录：确保 cd 参数指向正确且存在的目录 - - ⚠️ 错误处理：检查返回值的 success 字段，处理可能的错误 - -``` - -
- - - ---- - -## 🔧 工具说明 - -
-点击查看codex工具参数说明 - -| 参数 | 类型 | 必填 | 默认值 | 说明 | -|------|------|------|--------|------| -| `PROMPT` | `str` | ✅ | - | 发送给 Codex 的任务指令 | -| `cd` | `Path` | ✅ | - | Codex 工作目录根路径 | -| `sandbox` | `Literal` | ❌ | `"read-only"` | 沙箱策略：`read-only` / `workspace-write` / `danger-full-access` | -| `SESSION_ID` | `UUID \| None` | ❌ | `None` | 会话 ID（None 则开启新会话） | -| `skip_git_repo_check` | `bool` | ❌ | `False` | 是否允许在非 Git 仓库运行 | -| `return_all_messages` | `bool` | ❌ | `False` | 是否返回完整推理信息 | - -
- -
-点击查看codex工具返回值结构 - -**成功时：** -```json -{ - "success": true, - "SESSION_ID": "550e8400-e29b-41d4-a716-446655440000", - "agent_messages": "Codex 的回复内容...", - "all_messages": [...] // 仅当 return_all_messages=True 时包含 -} -``` - -**失败时：** -```json -{ - "success": false, - "error": "错误信息描述" -} -``` - -
- ---- - -## ❓ FAQ - -
-Q1: 是否需要额外付费？ - - CodexMCP 本身完全免费开源（MIT 许可证），**无需任何额外付费！** - -
- -
-Q2: 并行调用会冲突吗？ - - 不会。每个调用使用独立的 `SESSION_ID`，完全隔离。 - -
- - ---- - -## 🤝 贡献指南 - -
-我们欢迎所有形式的贡献！ - -### 开发环境配置 - -```bash -# 克隆仓库 -git clone https://github.com/GuDaStudio/codexmcp.git -cd codexmcp - -# 安装依赖 -uv sync -``` - -### 提交规范 - -- 遵循 [Conventional Commits](https://www.conventionalcommits.org/) -- 提交测试用例 -- 更新文档 - -
- - - ---- - -## 📄 许可证 - -本项目采用 [MIT License](LICENSE) 开源协议。Copyright (c) 2025 [guda.studio](mailto:gudaclaude@gmail.com) - ---- - -**用 🌟 为本项目助力** - -[![Star History Chart](https://api.star-history.com/svg?repos=GuDaStudio/codexmcp&type=date&legend=top-left)](https://www.star-history.com/#GuDaStudio/codexmcp&type=date&legend=top-left) \ No newline at end of file diff --git a/docs/README_EN.md b/docs/README_EN.md new file mode 100644 index 0000000..aa10cc4 --- /dev/null +++ b/docs/README_EN.md @@ -0,0 +1,261 @@ +![CodexMCP](../images/title.png) + +
+ + +**Seamlessly Bridge Claude Code and Codex** + +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/) [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)[![Share](https://img.shields.io/badge/share-000000?logo=x&logoColor=white)](https://x.com/intent/tweet?text=CodexMCP：Seamlessly%20bridge%20Claude%20Code%20and%20Codex%20https://github.com/GuDaStudio/codexmcp%20%23AI%20%23Coding%20%23MCP) [![Share](https://img.shields.io/badge/share-1877F2?logo=facebook&logoColor=white)](https://www.facebook.com/sharer/sharer.php?u=https://github.com/GuDaStudio/codexmcp) [![Share](https://img.shields.io/badge/share-FF4500?logo=reddit&logoColor=white)](https://www.reddit.com/submit?title=CodexMCP：Seamlessly%20bridge%20Claude%20Code%20and%20Codex&url=https://github.com/GuDaStudio/codexmcp) [![Share](https://img.shields.io/badge/share-0088CC?logo=telegram&logoColor=white)](https://t.me/share/url?url=https://github.com/GuDaStudio/codexmcp&text=CodexMCP：Seamlessly%20bridge%20Claude%20Code%20and%20Codex) + + +⭐ Star us on GitHub — Your support means the world! 🙏😊 + +English | [简体中文](../README.md) + +
+ +--- + +## 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](https://docs.claude.com/docs/claude-code) +- [Codex CLI Installation Guide](https://developers.openai.com/codex/quickstart) + + + +### 1. Installation Steps + +**1.1** Remove the official Codex MCP (if previously installed). + +```bash +claude mcp remove codex +``` + +**1.2** Install CodexMCP. + +```bash +claude mcp add codex --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:** +```json +{ + "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:** +```json +{ + "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 + +```bash +# Clone the repository +git clone https://github.com/GuDaStudio/codexmcp.git +cd codexmcp + +# Install dependencies +uv sync +``` + +### Commit Guidelines + +- Follow [Conventional Commits](https://www.conventionalcommits.org/) +- Include test cases +- Update documentation + +
+ + + +--- + +## 📄 License + +This project is licensed under the [MIT License](LICENSE). +Copyright (c) 2025 [guda.studio](mailto:gudaclaude@gmail.com) + +--- +
+Support us with a 🌟~ + +[![Star History Chart](https://api.star-history.com/svg?repos=GuDaStudio/codexmcp&type=date&legend=top-left)](https://www.star-history.com/#GuDaStudio/codexmcp&type=date&legend=top-left) +