MCPcopy Index your code
hub / github.com/congwa/codex-autoresearch

github.com/congwa/codex-autoresearch @v0.1.4

Chat with this repo
repository ↗ · DeepWiki ↗ · release v0.1.4 ↗ · + Follow
134 symbols 337 edges 18 files 32 documented · 24%
What it actually does AI analysis from the code graph — generated when you open this
loading…
README

codex-autoresearch

一个围绕 Codex CLI 的长任务包装器：开一个 Codex 对话把任务给它，模型干一部分活停了，自动 resume 同一个对话说“继续”，循环直到全部做完。

工作流程

用户                              codex-autoresearch                          Codex CLI (Worker)
 |                                      |                                          |
 |  codex-autoresearch --prompt-file    |                                          |
 | -----------------------------------> |                                          |
 |                                      |                                          |
 |                                      |  ensureJobMetadata                       |
 |                                      |  创建 .codex-run/<job-id>/meta.json      |
 |                                      |                                          |
 |                                      |  ========== runLoop 开始 ==========      |
 |                                      |                                          |
 |                                      |  buildInitialPrompt:                     |
 |                                      |    任务文本 + 执行边界 + completion protocol |
 |                                      |                                          |
 |                                      |  codex exec --full-auto <prompt>         |
 |                                      | ---------------------------------------->|
 |                                      |                                          | 开始执行任务...
 |                                      |                                          | context 用完 / 惰性停止
 |                                      |  <-- exit ------------------------------>|
 |                                      |                                          |
 |                                      |  检查 last-message.txt                   |
 |                                      |  没有匹配 completion protocol            |
 |                                      |  等 3 秒                                 |
 |                                      |                                          |
 |                                      |  codex exec resume <session-id> "继续"    |
 |                                      | ---------------------------------------->|
 |                                      |                                          | 接着执行...
 |                                      |                                          | 又停了
 |                                      |  <-- exit ------------------------------>|
 |                                      |                                          |
 |                                      |  ... 重复 N 轮 ...                       |
 |                                      |                                          |
 |                                      |  匹配 completion protocol                |
 |                                      |  校验 completion_report / 冻结目标       |
 |                                      |  status -> completed                     |
 |                                      |                                          |
 |  <-- 返回 {status: completed, ...}   |                                          |

关键设计： - 永动机核心循环：codex exec → 退出 → codex exec resume "继续" → 退出 → 循环 - 规划型任务支持“冻结目标 + 可变规划”：规划文件可以修正，但冻结目标不会变 - CLI 默认阻塞直到任务完成

安装

从 npm 全局安装（推荐）

npm install -g codex-autoresearch
codex-autoresearch --help
codex-autoresearch --version

从源码安装

git clone https://github.com/congwa/codex-autoresearch.git
cd codex-autoresearch
npm install
npm run build
npm link
codex-autoresearch --help
codex-autoresearch --version

快速开始

1. 查看版本

codex-autoresearch --version

2. 用规划文件驱动长任务

站在目标项目目录里，准备一个规划型 prompt.md：

# 任务规划

## 目标
- 完成接口文档
- 完成 CLI 示例
- 更新 README

## 执行步骤
- 先读代码
- 再落盘修改
- 最后自检

然后执行：

codex-autoresearch --prompt-file ./prompt.md

3. 显式传冻结目标

如果你担心规划文件后续会继续修正，或者末尾目标会被误删，推荐显式传冻结目标文本：

codex-autoresearch \
  --prompt-file ./prompt.md \
  --frozen-goals-text "- 完成接口文档
- 完成 CLI 示例
- 更新 README"

这时： - prompt.md 仍然可以继续修正 - 冻结目标以 --frozen-goals-text 为准 - 后续 resume 和完成判定都围绕这份冻结目标工作

使用方式

prompt.md + CLI（推荐）

站在目标项目目录里，准备好一个 prompt.md 文件，然后：

codex-autoresearch --prompt-file ./prompt.md
# 或
codex-autoresearch run --prompt-file ./prompt.md

带冻结目标：

codex-autoresearch run \
  --prompt-file ./prompt.md \
  --frozen-goals-text "- 目标1
- 目标2"

直接传任务文本

codex-autoresearch "请检查当前仓库 TODO，补齐缺失测试并更新 README"

常用命令

# 查看帮助
codex-autoresearch --help

# 查看版本
codex-autoresearch --version

# 恢复最近一次任务
codex-autoresearch session resume --last

# 查看最近任务状态
codex-autoresearch session status --last

Shell 薄包装 codex-keep-running.sh

./codex-keep-running.sh ./prompt.md
cat ./prompt.md | ./codex-keep-running.sh -

环境变量：

变量 作用
WORKDIR 实际执行目录
STATE_DIR 状态根目录
INTERVAL 重试间隔
MODEL 模型
PROFILE profile
USE_FULL_AUTO 是否开启 --full-auto
DANGEROUSLY_BYPASS 是否启用危险绕过模式
SKIP_GIT_REPO_CHECK 是否跳过 git 校验
START_WITH_RESUME_IF_POSSIBLE 是否优先从历史状态恢复
CONFIRM_TEXT 自定义完成确认文本

.codex-run 状态模型

统一执行引擎会把状态写到：

.codex-run/<job-id>/

典型文件：

文件 作用
meta.json 任务元信息、状态、配置、prompt 来源
events.jsonl Codex JSON 事件流
runner.log 执行日志和错误输出
last-message.txt 最近一轮 assistant 最终输出
session-id.txt 从事件流提取的 session id
goal-contract.md 冻结目标契约，后续不再受规划文件改动影响
goal-manifest.json 结构化冻结目标清单，供完成对账使用
working-plan.latest.md 当前最新规划文件快照
plan-revisions.jsonl 每次检测到规划文件变化时追加一条修订记录

meta.json 中记录的 prompt 来源字段：

字段 说明
promptSource "file" / "text"
sourcePromptFile 原始 prompt 文件绝对路径（仅 promptSource: "file" 时有值）
goalExtractionMode 冻结目标来源：cli_text / explicit_section / full_file_fallback
goalContractHash 冻结目标内容哈希
lastObservedPlanHash 最近一次观测到的规划文件哈希
lastCompletionCheck 最近一次完成校验结果
lastPlanDrift 当前规划是否偏离冻结目标的说明

规划型任务的推荐写法

推荐把规划文件拆成两层：

  1. 不可变目标
  2. 可变执行计划

推荐模板：

# 任务规划

## 目标
- 目标 A
- 目标 B
- 目标 C

## 执行步骤
- 这部分允许继续修正
- 可以调整顺序
- 可以补充过程说明

如果你需要最稳的行为，优先使用 --frozen-goals-text，这样就不会再依赖自动提取。

恢复、查看状态

# 恢复最近一次任务
codex-autoresearch session resume --last

# 查看最近任务状态
codex-autoresearch session status --last

# 按 session id 继续
codex-autoresearch session resume <session-id>

Completion Protocol

执行引擎要求 Codex 在真正完成时，把 completion protocol 放在最终两行：

  1. 基于 nonce 反转后的 done token
  2. CONFIRMED: all tasks completed

对于规划型任务，还要求在这两行之前输出：

<completion_report>
- [x] 冻结目标 1
- [x] 冻结目标 2
</completion_report>

只有同时满足下面条件才会标记为 completed：

  • 最终两行匹配 completion protocol
  • 没有阻断型 MCP/tool 失败
  • completion_report 覆盖全部冻结目标

如果 completion_report 缺项，任务会继续保持 needs_resume。

测试

npm test

本地开发

npm install
npm run build
npm link
codex-autoresearch --help
codex-autoresearch --version

Extension points exported contracts — how you extend this code

NormalizedRunOptions (Interface)
* 业务职责：规范化后的运行选项代表执行引擎内部真正依赖的稳定配置， * 让默认值、路径解析和安全开关在进入主循环前一次性收口。
src/engine/job.ts
CliExecutionOptions (Interface)
(no doc)
src/application/context.ts
StreamCallbacks (Interface)
(no doc)
src/presenters/streaming.ts
RunTaskOptions (Interface)
(no doc)
src/engine/job.ts
NormalizedCliExecutionContext (Interface)
(no doc)
src/application/context.ts
ResumeSessionOptions (Interface)
(no doc)
src/engine/job.ts
CommandExecutionContext (Interface)
(no doc)
src/application/types.ts
TailSessionOptions (Interface)
(no doc)
src/engine/job.ts

Core symbols most depended-on inside this repo

c
called by 16
src/presenters/streaming.ts
write
called by 10
src/presenters/streaming.ts
writeJobMetadata
called by 9
src/engine/state.ts
printResult
called by 8
src/cli.ts
buildResult
called by 7
src/engine/job.ts
startSpinner
called by 7
src/presenters/streaming.ts
shortenPath
called by 7
src/presenters/streaming.ts
maybeStreamCallbacks
called by 6
src/cli.ts

Shape

Function 106
Interface 25
Class 2
Method 1

Languages

TypeScript100%

Modules by API surface

src/engine/planning.ts25 symbols
src/engine/job.ts25 symbols
src/presenters/streaming.ts19 symbols
src/engine/state.ts19 symbols
src/cli.ts11 symbols
src/application/types.ts7 symbols
src/engine/error.ts6 symbols
src/application/use-cases.ts5 symbols
src/engine/completion.ts4 symbols
src/engine/codex.ts4 symbols
src/presenters/json.ts3 symbols
src/application/context.ts3 symbols

For agents

$ claude mcp add codex-autoresearch \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact