Cook：编排Claude Code的轻量级CLI工具

xN

xN 按顺序运行工作 N 次，每次执行都能看到前一次的输出。

cook "Add dark mode" x3           # 3 sequential passes
cook "Add dark mode" repeat 3     # long-form
cook "Add dark mode" x3 review    # 3 passes, then a review loop
cook "Add dark mode" review x3    # review loop repeated 3 times

review

review 添加一个 review→gate 循环。完成工作后，由审查者检查质量，gate 决定 DONE 或 ITERATE。在 ITERATE 时，运行 iterate 步骤，然后重复 review→gate。

cook "Add dark mode" review           # default prompts, up to 3 iterations
cook "Add dark mode" review 5         # up to 5 iterations

在 review 后提供自定义 prompt，或使用位置简写：

# Explicit
cook "Add dark mode" review \
     "Review for accessibility" \
     "DONE if WCAG AA, else ITERATE"

# Shorthand — same result
cook "Add dark mode" \
     "Review for accessibility" \
     "DONE if WCAG AA, else ITERATE"

# With iterate prompt and max-iterations
cook "Add dark mode" \
     "Review for accessibility" \
     "DONE if WCAG AA, else ITERATE" \
     "Fix the issues" 5

为每个步骤使用不同的 agent 或模型：

cook "Add dark mode" review \
  --work-agent codex --work-model gpt-5-codex \
  --review-agent claude --review-model opus

ralph

Ralph 在 cook 外层添加一个 gate，用于任务列表的进度推进。工作 prompt 是自指导的——它每次都读取项目状态来找到当前任务。

cook "Work on next task in plan.md" \
     ralph 5 "DONE if all tasks complete, else NEXT"

# review gate per task, then ralph advances
cook "Work on next task in plan.md" \
     review "Code review" "DONE if no High issues, else ITERATE" \
     ralph 5 "DONE if all tasks complete, else NEXT"

review gate 决定 DONE（传递给 ralph）或 ITERATE（修复并重试）。ralph gate 决定 DONE（退出）或 NEXT（推进到下一个任务，重置迭代计数）。

组合操作符

组合操作符在并行隔离的 git worktree 中运行多个 cook，然后用 resolver 合并结果。

versions（vN / race N）

vN 在并行 worktree 中运行 N 个相同的 cook。pick 是默认的 resolver。

cook "Add dark mode" v3                       # 3 runs, pick the best
cook "Add dark mode" v3 "least code wins"     # with pick criteria
cook "Add dark mode" race 3 "least code wins" # long-form alias

cook "Add dark mode" review v3 "cleanest"      # race 3, each with a review loop
cook "Add dark mode" x3 v3 "most complete"     # race 3, each with 3 passes

vs

vs 在并行 worktree 中运行两个不同的 cook。每个分支都是一个完整的 cook——它可以有自己的循环操作符。

cook "Implement auth with JWT" \
  vs \
  "Implement auth with sessions" \
  pick "best security"

cook "Build with React" review "Check accessibility" "DONE if WCAG AA" 3 \
  vs \
  "Build with Vue" review "Check bundle size" "DONE if under 50kb" 5 \
  merge "best developer experience"

初始化

在项目根目录运行 cook init 来搭建配置文件：

cook init

COOK.md——项目说明和 agent prompt 模板

.cook/config.json——agent/model/sandbox 默认值和每步配置覆盖

.cook/Dockerfile——Docker sandbox 模式下的项目依赖

.cook/logs/——会话日志（gitignored）

示例 .cook/config.json：

{
  "agent": "claude",
  "sandbox": "agent",
  "steps": {
    "work":    { "agent": "codex",  "model": "gpt-5-codex" },
    "review":  { "agent": "claude", "model": "opus" }
  },
  "env": ["CLAUDE_CODE_OAUTH_TOKEN"]
}

注：OpenCode 仅在 Docker 模式下支持。

Docker 网络

默认情况下，Docker sandbox 限制出站流量仅为每个 agent 所需的内容。在 .cook/config.json 中配置：

{
  "docker": {
    "network": {
      "mode": "restricted",
      "allowedHosts": ["api.mycompany.com"]
    }
  }
}

allowedHosts 在 mode 为"restricted"时向白名单添加额外主机。

令牌配额和速率限制

当 agent 触发令牌配额或速率限制时，cook 自动等待并重试，而不是直接失败。TUI 中显示倒计时。默认启用。

cook "Build the feature" review --no-wait   # disable: fail fast

在 .cook/config.json 中配置等待行为：

{
  "retry": {
    "enabled": true,
    "pollIntervalMinutes": 5,
    "maxWaitMinutes": 360
  }
}