内容
<div align="center">
# 代码执行管理
**与 Claude 规划 · 使用 OpenAI Codex 执行 · 与 Claude 评审**
一个 Claude Code 插件和 MCP 服务器，运行有纪律的 **规划 → 执行 → 评审** 循环：
Claude 与您交谈并设计规划，Codex 编写代码，然后 Claude 评审每个任务
和最终检查，以及所需的 Codex `codex_review`；查找结果进行比较，修复返回，
非阻塞改进等待您的决定 — 所有操作都从单个命令开始。
[](https://github.com/anhnguyen0905/codex-mcp/actions/workflows/ci.yml)
· macOS · Windows · Linux · Node ≥ 20 · MIT
</div>
---
## 快速开始
**1. 先决条件** — Node ≥ 20 和 Codex CLI，已验证：
```bash
npm i -g @openai/codex
codex login # ChatGPT Plus/Pro/Team — 或设置 OPENAI_API_KEY
```
**2. 安装插件** （捆绑 `/codex-flow` 命令 + `codex` MCP 服务器）：
```
/plugin marketplace add anhnguyen0905/codex-mcp
/plugin install codex-flow@codex-mcp
```
**3. 在任何项目中运行**：
```
/codex-flow 实现设置页面上的暗黑模式切换
```
<details>
<summary>替代：单独安装 MCP 服务器（无插件）</summary>
```bash
# 从 npm
claude mcp add --scope user codex -- npx -y @anhnguyen0905/codex-mcp
# 或直接从此存储库
claude mcp add --scope user codex -- npx -y github:anhnguyen0905/codex-mcp
```
`claude mcp list` 然后应显示 `codex … ✔ 已连接`。复制
[`commands/codex-flow.md`](commands/codex-flow.md) 到 `~/.claude/commands/` 以获取工作流
命令，或仅使用上述插件安装程序，后者同时包含两者。
</details>
---
## 工作原理
```
Claude Code ──(MCP stdio)──▶ codex-mcp ──spawns──▶ codex exec --json
```
`/codex-flow` 运行六个阶段，保持 Claude 作为规划者/评审者和 Codex 作为执行者：
| 阶段 | 所有者 | 发生情况 |
|-------|-------|--------------|
| **0 · 预检查** | Claude | 验证 Codex 登录；基线 git + 测试；恢复中断的运行。 |
| **1 · 面试** | Claude | 澄清需求，直到每个验收标准可验证。 |
| **2 · 规划** | Claude | 探索代码库，选择相关技能，编写 `.codex-flow/PLAN.md`。 |
| **3 · 待办事项** | Claude | 分解为依赖有序的任务，位于 `.codex-flow/TASKS.md`。 |
| **4 · 执行** | Codex | 实施一个或多个任务（或并行执行，见下文）。 |
| **5 · 评审** | Claude + Codex | 通过 Claude + 必需的 `codex_review` 进行双重评审每个任务和最终检查；比较发现，循环修复返回，并收集非阻塞改进以供用户决策。 |
捆绑的 `session-report` 技能将每个会话的捆绑包写入 `.codex-flow/reports/<YYYYMMDD-HHMMSS>/`，包含规划、分配、任务、成本和摘要报告，以及明确的 `claude` / `codex` / `both` PIC 属性。
服务器以非交互方式启动 `codex exec`，解析其 JSONL 事件流，并返回结构化结果（`sessionId`、`agentMessage`、`fileChanges`、`commands`、`token usage`、`diff`）。
---
## 亮点
### 基于索引的技能选择
与盲目加载整个技能集合不同，`/codex-flow` 仅为任务选择所需的技能
从**本地索引**：它对请求角色方面（工程、数据、
营销、设计……）进行分类，并加载每个相关技能
符合上下文预算（约 3% 的窗口），将提炼的规则块嵌入到 Codex 提示中。磁盘上的技能在选择之前成本为零；
第三方技能在首次使用前经过验证。
```bash
node scripts/sync-awesome-skills.mjs --clone # 从 awesome-claude-skills 构建本地库
node scripts/build-skills-index.mjs # → ~/.claude/skill-library/INDEX.md
```
通过 32 个场景范围评估（`npm run skills:eval`）验证 - 最新 **32/32**。完整过程：
[`skills/skill-selection/SKILL.md`](skills/skill-selection/SKILL.md)。
### 大型待办事项的并行执行
codex-mcp 序列化每个工作区的运行，但跨工作区并行化，因此独立任务
可以**并发**运行 - 每个任务都在自己的 git 工作树中由 Claude 子代理驱动，然后合并
并按波浪进行集成评审。
```bash
npm run waves # 从 .codex-flow/TASKS.md 计算执行波浪
```
波浪批次任务的依赖关系已满足，文件是分离的，限制在 **10
并发子代理**（`--max <n>`降低）。选择加入；成本 N× 同时限额。攻略：
[`skills/parallel-execution/SKILL.md`](skills/parallel-execution/SKILL.md)。
---
## 工具
| 工具 | 目的 |
|------|---------|
| `codex_execute` | 启动执行任务/规划的新 Codex 会话 |
| `codex_continue` | 恢复具有后续（例如，评审反馈）的会话 |
| `codex_review` | 只读评审未提交的工作区更改 |
| `codex_batch` | 在不同工作区（工作树）上并行运行多达 50 个任务 |
| `codex_sessions` | 列出以前的 Codex 会话（来自 `~/.codex/sessions/`），可按 cwd 过滤 |
| `codex_metrics` | 从本地运行日志聚合令牌/持续时间/失败指标 |
| `codex_health` | 检查 Codex CLI 版本和登录状态 |
`codex_execute` / `codex_continue` / `codex_review` 接受 `writeNotes: true` 以将运行的 markdown
摘要保存到 `<cwd>/.codex-flow/notes/<sessionId>.md`。
沙盒模式：`read-only`，`workspace-write`（默认），`danger-full-access`。默认执行
超时为 30 分钟（`timeoutMs`上限为 2 小时）。运行到同一个 `cwd` 是序列化的；不同的
工作区并行运行。
<details>
<summary>结果有效载荷和实时进度</summary>
每个运行工具都返回 `sessionId`、`agentMessage`、`fileChanges`、`commands`、`token usage`、
`errors`，以及：
- **`diff`** — `git status --porcelain` + 在运行后 `git diff HEAD` （64 KB 限制，`truncated`
标志；`null`在 git 仓库外），以便调用者可以在不重新读取文件的情况下进行评审。
- **`aborted`** — 当客户端取消（Claude Code 中的 Esc）；服务器将取消
发送到 Codex（SIGTERM → 5 秒后 SIGKILL）。
- **`liveLog`** — 当启用实时终端视图时，原始 JSONL 事件日志的路径。
发送 MCP `progressToken` 的客户端（Claude Code 执行）获取每个
有意义的 Codex 事件的 `notifications/progress`。设置 `terminal: true`（或 `CODEX_MCP_TERMINAL=1`）还会打开
实时跟踪窗口 — macOS 上的 Terminal.app，Windows 上的 PowerShell，Linux 上的第一个可用模拟器。如果没有
可以打开窗口，运行仍然成功；跟随 `liveLog` 或会话内的进度。
</details>
---
## 配置
| 变量 | 效果 |
|----------|--------|
| `OPENAI_API_KEY` | Codex CLI 的身份验证（替代 `codex login`）。 |
| `CODEX_BIN` | 覆盖 Codex 二进制路径/名称（例如 `C:\tools\codex.exe`）。 |
| `CODEX_MCP_TERMINAL=1` | 默认打开实时进度窗口。 |
| `CODEX_FLOW_SKILLS_INDEX` | 覆盖技能索引路径。 |
| `MCP_TOOL_TIMEOUT` | 提高 Claude Code 的 MCP 工具超时时间（毫秒）以适应长时间运行。 |
> **安全：** 服务器从不读取、存储或传输您的凭证 — 认证完全由
> Codex CLI（`~/.codex/`）处理。运行 `npm run doctor` 以验证您的设置。
---
## 开发
```bash
npm test # 单元测试（vitest）
npm run coverage # 强制执行 80% 阈值
npm run build # tsc → dist/
npm run test:e2e # 真实端到端烟雾测试（启动 Codex，使用配额）
```
<details>
<summary>源代码布局</summary>
**服务器**（`src/`）：`index.ts`（stdio 入口）· `server.ts`（MCP 工具，cwd 锁定，取消） ·
`argsBuilder.ts`（argv）· `codexRunner.ts`（启动 + 超时/杀死）· `eventParser.ts`（JSONL →
结果）· `workspaceDiff.ts`（git diff）· `terminal.ts` / `liveView.ts` / `progressFormatter.ts` /
`progressNotifier.ts`（实时进度）。
**技能和工作流脚本**（`scripts/`）：`sync-awesome-skills.mjs` · `build-skills-index.mjs` ·
`skill-match.mjs` · `skill-eval.mjs` · `task-waves.mjs` · `session-cost.mjs` · `tail-progress.mjs`。
</details>
---
<div align="center">
<sub>MIT · <a href="CHANGELOG.md">更新日志</a></sub>
</div>
