CriticLoop

CriticLoop 是一个目标驱动的 Claude Code 多智能体 CLI。你传入一个目标和一个工作目录，它会让 brain -> executor -> verifier -> evaluator 循环协作：先规划，再写文件，跑确定性验收，再基于证据批评并继续修改，直到通过或达到迭代上限。

critic-loop --cwd ./runs/xxxxx "构建一个名为 xxxxx 的应用"

What It Is

CriticLoop 的定位是 CLI，不是要嵌进你代码里的 SDK。它适合在一个隔离目录里从自然语言目标生成项目、修复项目、补测试、写工具或整理文档。

能力	状态
目标驱动 CLI	传入目标和 --cwd 后自动规划、执行、验收。
Claude Code 接入	brain、executor、evaluator 都调用 Claude Code CLI。
角色隔离	默认给三个角色分配独立 Claude session，resume 时复用。
确定性验收	--verify-command 可重复传入，退出码会作为 evaluator 的硬证据。
白盒输出	默认使用 Claude Code stream-json 显示 live progress 和结构化回答。
运行报告	默认写 .critic-loop/run-*.json 和 .critic-loop/latest.json。
断点续跑	--resume 读取 latest report，跳过 brain 并从下一轮继续。
显式状态	CriticLoop 保存 checkpoint、history、evidence，不替代 Claude Code 内部上下文。

Quick Start

先确认本机已经配置好 Claude Code CLI：

claude --version

从源码运行：

git clone git@github.com:Lin-A1/CriticLoop.git
cd CriticLoop
npm install
npm run build

node dist/cli.js \
  --cwd ./runs/xxxxx \
  --max-iterations 3 \
  --verify-command "test -f README.md" \
  "构建一个名为 xxxxx 的小型项目，生成 README.md，并说明如何运行。"

作为命令使用：

npm install -g critic-loop
critic-loop --cwd ./runs/xxxxx "构建一个名为 xxxxx 的应用"

--cwd 不存在时会自动创建。建议每个目标使用独立目录，例如 ./runs/app-a、./runs/tool-b。

Write A Good Goal

目标最好写成任务单，而不是一句愿望。一个可执行目标通常包含这些部分：

Part	Example
产物范围	只生成 index.html、style.css、script.js、README.md。
功能要求	支持 CRUD、筛选、统计、本地保存、导入导出。
约束	不使用构建工具、npm 包、CDN 或外部资源。
验收标准	页面可直接打开；README 说明运行方式；脚本通过语法检查。
验证命令	--verify-command "node --check script.js"

示例：

critic-loop \
  --cwd ./runs/task-board \
  --max-iterations 3 \
  --verify-command "node --check script.js" \
  --verify-command "test -f index.html && test -f README.md" \
  "构建一个无依赖静态任务看板。
  只生成 index.html、style.css、script.js、README.md。
  功能：任务增删改查、筛选、统计、本地 localStorage 保存、导入导出。
  质量：响应式布局、键盘可用、错误状态清晰。
  验收标准：页面可直接打开；README 说明如何运行；script.js 通过 node --check。"

也可以从文件读取目标：

cat goal.md | critic-loop --cwd ./runs/xxxxx --verify-command "npm test"

Runtime Flow

每一轮的核心数据流：

Role	Input	Output
brain	userGoal、上一轮 plan	taskPlan、evaluationPlan、initialPrompt
executor	plan、private memory、shared history、critique	summary、observations、artifacts
verifier	用户提供的本地命令	VerificationResult[]：exit code、stdout、stderr
evaluator	artifacts 快照、verification results、history	passed、score、critique、requiredChanges

最小输出协议：

{
  "taskPlan": { "objective": "string", "steps": ["string"] },
  "evaluationPlan": {
    "checks": ["string"],
    "passCriteria": ["string"],
    "maxIterations": 3
  },
  "initialPrompt": "string",
  "confirmed": true
}

{
  "summary": "string",
  "observations": ["string"],
  "artifacts": ["index.html", "style.css", "script.js", "README.md"]
}

{
  "passed": false,
  "score": 0.75,
  "critique": "string",
  "requiredChanges": ["string"],
  "observations": ["string"]
}

White-Box Mode

默认终端会显示两类白盒信息：

• Claude Code 运行中的 live progress：默认解析 stream-json，显示 init、message、text delta、tool、result 等事件；如果长时间没有 chunk，会显示 heartbeat。
• brain、executor、evaluator 完成后交给 loop 的结构化 JSON。

critic-loop \
  --cwd ./runs/xxxxx \
  "构建一个小型 CLI 工具"

结构化输出会带上 agent name、request id、耗时和 raw 长度。需要原始 Claude stdout/stderr 时，再加 --raw-events 并查看 run report。CLI 不会打印 thinking delta 原文，只会提示存在 thinking event。

关闭白盒输出：

critic-loop --cwd ./runs/xxxxx --no-agent-output --no-agent-progress "构建一个小型 CLI 工具"

Reports And Resume

默认每次运行都会写两份报告：

./runs/xxxxx/.critic-loop/run-2026-06-02T12-00-00-000Z.json
./runs/xxxxx/.critic-loop/latest.json

报告包含 goal、CLI 参数、loop events、最终 result 或 error、verifier stdout/stderr 摘要。可以用 --report ./report.json 指定路径，用 --no-report 关闭。

未通过或中断后继续：

critic-loop --cwd ./runs/xxxxx --resume

--resume 默认读取 ./runs/xxxxx/.critic-loop/latest.json。如果要从指定报告恢复：

critic-loop \
  --cwd ./runs/xxxxx \
  --resume-from ./runs/xxxxx/.critic-loop/run-2026-06-02T12-00-00-000Z.json

恢复时会复用上次的 Claude session id、brain plan、history、executor memory、evaluator memory 和最后一轮 critique，并从下一轮 iteration 开始。此时 --max-iterations 表示本次继续运行的额外迭代预算，默认 3。

Memory Isolation

默认情况下，CriticLoop 会让 Claude Code 保存内部会话，并把三个角色的 session id 写入 run report：

brain     -> 独立 Claude session
executor  -> 独立 Claude session
evaluator -> 独立 Claude session

这样 executor/evaluator 可以利用 Claude Code 自己的项目上下文和大文件处理能力，同时避免三个角色互相污染。CriticLoop 维护的 history/memory/report 是显式 checkpoint 和审计信息，不是主要的大文件上下文来源。如果需要完全关闭 Claude Code session 落盘，可加 --no-claude-sessions。

CLI Options

critic-loop "your goal" [options]

Option	Description
--cwd <path>	工作目录，默认当前目录。不存在时自动创建。
--model <name>	Claude Code 模型，默认使用本机 Claude CLI 默认模型。
--report <path>	指定运行报告 JSON 路径。
--no-report	关闭默认 .critic-loop 运行报告。
--resume	从 <cwd>/.critic-loop/latest.json 断点续跑。
--resume-from <path>	从指定 run report JSON 断点续跑。
--no-claude-sessions	禁用 Claude Code 内部 session 持久化。
--max-brain-rounds <n>	brain 方案确认轮数，默认 2。
--max-iterations <n>	executor/evaluator 循环轮数，默认 3。
--history-policy <none|previous|full>	共享历史策略，默认 previous。
--verify-command <cmd>	executor 后运行的确定性验收命令，可重复传入。
--verification-timeout-ms <n>	单条验收命令超时，默认 120000。
--timeout-ms <n>	给所有 agent 设置相同超时。
--brain-timeout-ms <n>	brain 超时，默认 120000。
--executor-timeout-ms <n>	executor 超时，默认 600000。
--evaluator-timeout-ms <n>	evaluator 超时，默认 180000。
--executor-permission-mode <mode>	executor 的 Claude 权限模式，默认 acceptEdits。
--default-permissions	executor 使用 Claude CLI 默认权限。
--bypass-permissions	executor 使用 bypassPermissions，只适合可信沙箱目录。
--context <json>	合并 JSON object 到 sharedContext。
--raw-events	在事件中包含模型原始输出。
--show-agent-output	打印 brain/executor/evaluator 的结构化回答，默认开启。
--no-agent-output	隐藏 agent 结构化回答。
--show-agent-progress	显示 Claude Code live progress 和 heartbeat，默认开启。
--no-agent-progress	隐藏 Claude Code live progress 和 heartbeat。
--fail-fast-brain	brain 错误或超时时立即失败。
--fail-fast-executor	executor 错误或超时时立即失败。
--fail-fast-evaluator	evaluator 错误或超时时立即失败。
--json	输出完整 LoopResult JSON。
-h, --help	显示帮助。
-v, --version	显示版本。

退出码：

Code	Meaning
0	evaluator 通过，且 verifier 没有失败。
1	运行时错误。
2	loop 跑完，但 evaluator 仍未通过。

Project Layout

src/cli.ts                     CLI entry
src/index.ts                   core runtime and Claude Code agents
scripts/generate-doc-assets.mjs reproducible README flow diagrams
test/runtime.test.mjs          runtime and CLI tests
docs/images                    generated flow and contract diagrams
.critic-loop                   default local run reports, ignored by git
README.md                      CLI usage guide

仓库不再附带旧 examples/。实际产物由你通过 --cwd 指定输出目录生成。

Development

npm run build
node dist/cli.js --help
npm run docs:assets
npm run verify
npm pack --dry-run

npm run verify 会执行类型检查、单元测试和格式检查。npm run docs:assets 会重新生成 README 使用的三张流程图。