Ralph Codex

Ralph Codex 是面向 Codex 的 Ralph 任务执行器，作为 npm CLI 发布。它把通用 runner 放在 npm 包内，把每个项目自己的任务状态放在项目根目录的 .ralph/ 下。

安装

在目标 git 项目里安装并初始化：

pnpm add -D @lukecai/ralph-codex
pnpm exec ralph init

安装后先提交或暂存 package.json 和 lockfile，再开始跑任务，避免把依赖变更混进业务提交。

日常入口

创建任务：

pnpm exec ralph new "Task name" --task "Requirement or confirmed proposed_plan"
pnpm exec ralph run

Codex 桌面版建议使用低噪声入口：

pnpm exec ralph new "Task name" --task "Requirement or confirmed proposed_plan"
pnpm exec ralph run-desktop

普通终端或需要完整 stdout/stderr 时：

pnpm exec ralph run

第一次创建任务后，new 会写入 .ralph/state/current-prompt.md。先把这个 prompt 交给 Codex，让它生成 .ralph/tasks/work/<taskId>/prd.md 和 .ralph/tasks/work/<taskId>/prd.json，然后再执行 run 或 run-desktop。

常用命令

| 命令 | 用途 | | --- | --- | | pnpm exec ralph doctor | 检查本机和项目配置。 | | pnpm exec ralph current | 查看当前任务。 | | pnpm exec ralph run-desktop | Codex 桌面版执行或继续当前任务。 | | pnpm exec ralph run | 普通终端执行或继续当前任务。 | | pnpm exec ralph status | 查看 brief 运行状态；详细路径用 status --verbose。 | | pnpm exec ralph archive | 归档已完成任务。 |

完整参数和更多场景见 docs/usage.md，配置项见 docs/configuration.md。

更新版本

查看当前 npm 最新版本：

pnpm view @lukecai/ralph-codex version

更新项目内版本：

RALPH_REQUIRE_CLEAN_WORKTREE=false pnpm exec ralph run 1

更新或指定版本

项目内安装推荐使用 pnpm up -D 更新到 npm registry 上的 latest 版本；如果团队需要固定版本或回退版本，可以用 pnpm add -D @lukecai/ralph-codex@版本号 明确写入 package.json 和 lockfile。

pnpm view @lukecai/ralph-codex version
pnpm list @lukecai/ralph-codex
pnpm exec ralph --version
pnpm up -D @lukecai/ralph-codex@latest
pnpm exec ralph doctor

安装或回退到指定版本：

pnpm add -D @lukecai/[email protected]

如果你使用的是全局安装的 ralph，全局版本需要单独更新：

pnpm add -g @lukecai/ralph-codex@latest

.ralph/ 会写什么

Ralph 会维护项目内的 .ralph/：

• .ralph/config.json 和 .ralph/.gitignore 是团队共享配置，通常提交。
• .ralph/tasks/work/<taskId>/prd.md、prd.json、progress.txt 是任务状态，任务激活后通常提交。
• .ralph/state/、.ralph/runs/、.ralph/ralphrc 和 lock 文件是本地状态，默认忽略。

更多文档

• docs/usage.md：完整工作流、命令参数、排障、迁移说明。
• docs/configuration.md：配置文件、环境变量和优先级。
• docs/development.md：维护本 npm 包时的开发、测试和发布流程。