codex-runner

codex-runner 是一个面向 codex 的 Plan 执行器，用于按顺序执行 Markdown Plan 文件，并在本地落盘执行状态。

特性

• 串行执行：一次只执行一个 Plan（一个 md 对应一个 Codex Session）
• 同会话续跑：首轮 codex exec，后续统一 codex exec resume
• one-shot 模式：执行一轮后退出
• 完成协议：只认一次性 DONE_TOKEN + CONFIRM_TEXT，不认自然语言“完成”
• 失败不阻塞：单个 Plan 失败后跳过并继续后续 Plan
• 自动继续：检测到交互阻塞提示时自动输入 go on
• 可筛选执行：--plan-dir 支持目录和 glob 模式（仅匹配 .md 文件）
• 可自定义 Prompt：支持 --prompt-file 模板化执行提示
• 默认完全访问：执行 codex exec 时默认附带 --dangerously-bypass-approvals-and-sandbox

环境要求

• Node.js >= 20（推荐 22+）
• 本机可执行 codex 命令
• 包管理器：pnpm

快速开始

准备 Plan 目录：

mkdir -p docs/superpowers/plan

直接运行：

npx codex-runner

Plan 格式

每个 Plan 文件都是 *.md。frontmatter 是可选的。

字段说明：

• id：可选，默认取文件名（不含后缀）
• done_marker：可选，默认 PLAN_DONE，要求 Codex 最终输出该标记

纯 Markdown（也支持）：

# Plan 内容

实现 xxx
检查 yyy

当没有 frontmatter 时：

• id 默认使用文件名（不含 .md）
• done_marker 使用默认值 PLAN_DONE

CLI 用法

codex-runner \
  --plan-dir docs/superpowers/plan \
  --state-file .codex-runner/state.json \
  --prompt-file docs/superpowers/prompt.md

参数说明：

• --plan-dir <path>：Plan 目录或 glob 模式，默认 docs/superpowers/plan
• --state-file <path>：状态文件路径，默认 .codex-runner/state.json
• --prompt-file <path>：自定义 Prompt 模板文件（可选）

按日期前缀筛选 Plan：

codex-runner --plan-dir 'docs/superpowers/plan/2026-03-24*'

查看帮助：

codex-runner --help

Prompt 模板

--prompt-file 支持以下占位符：

• {{PLAN_FILE}}：当前 Plan 文件绝对路径
• {{PLAN_ID}}：当前 Plan 的 id
• {{DONE_MARKER}}：当前 Plan 的完成标记

示例：

请执行这个 plan：{{PLAN_FILE}}
完成后请原样输出：{{DONE_MARKER}}

执行语义

• 单个 Plan 成功条件：
• 本轮 last-message 严格等于两行（DONE_TOKEN + CONFIRM_TEXT，无第三行）
• 默认失败策略：当前 Plan 失败后继续下一个
• 退出码 0：全部 Plan 成功
• 退出码 2：执行完成但存在失败 Plan
• 每轮生成新的随机 nonce 与 DONE_TOKEN，避免历史输出误判
• 首轮若无法获取 sessionId，该 Plan 直接失败（避免偷偷新开会话）

状态文件

执行状态默认写入 .codex-runner/state.json。每个 Plan 会记录：

• status：running | success | failed
• reason：成功或失败原因
• 时间戳与轮次信息

开发与测试

pnpm test

测试基于 Node 原生工具链：node:test + assert/strict。

Acknowledge

https://github.com/congwa/codex-autoresearch