claude-forever

自主编码脚手架 -- 驱动 Claude Code 以完整交互模式循环完成复杂软件任务。

核心理念

claude-forever 是一个脚手架（Harness），而非控制器。基于 Anthropic 的 Effective Harnesses for Long-Running Agents 理念：

Claude Code 以交互模式运行，保留所有 Agent 能力（读写文件、执行命令、思考推理），完成后自动退出
CF 只管理轮间状态 -- 规划 Feature、启动会话、对抗评估、做 git 检查点
用户可以实时看到 Claude Code 的工作进度（通过 pexpect PTY 保留完整 TUI 交互体验）
Planner 和 Adversary 都是 CC Session -- CF 不直接调用 LLM API，一切决策通过 Claude Code 自身能力完成

安装

# 克隆仓库
git clone <本仓库地址>
cd claude-forever

# 推荐用 pipx 安装（全局可用，不污染系统 Python）
brew install pipx  # macOS，如已安装可跳过
pipx ensurepath
pipx install .

# 或直接 pip 安装
pip install .

安装完成后，cf 命令即可在任意目录使用。

前置要求

Claude Code CLI（claude），或 Gemini CLI
ECC 插件（Everything Claude Code） -- Planner 和 Adversary 的 CC Session 依赖 ECC 的 /plan、/verify 等技能

ECC 安装方法（在 Claude Code 交互会话中执行）：

/plugin marketplace add affaan-m/everything-claude-code
/plugin install everything-claude-code@everything-claude-code

可通过 cf init 一键检测 CLI 和 ECC 是否就绪。

配置

# 交互式配置向导（推荐）
cf config

配置向导分为 2 步：

选择 Executor -- 自动检测已安装的 CLI（claude / gemini）
通知配置（可选） -- 企业微信 Webhook，任务完成/失败时推送通知

配置保存在 ~/.claude-forever/.env。

注意：Planner 和 Adversary 现在都通过 CC Session 运行，不再需要单独配置 LLM 模型和 API Key。

使用

# 无参数启动（推荐）：打开 Dashboard UI，在界面中输入目标
cf run

# 快速启动一个新任务
cf run "开发一个带 JWT 认证的 REST API"

# 跳过 Plan Review，规划完成后自动开始执行
cf run --auto-approve "实现用户注册登录模块"

# 续跑最近的未完成任务
cf run --resume

# 查看当前任务状态
cf status

# 暂停 / 继续 / 停止
cf pause
cf resume
cf stop

# 只启动 Dashboard（不运行 Orchestrator）
cf dashboard

cf run 无参数时进入 Goal Entry 模式：Dashboard 在浏览器打开后显示目标输入表单，用户在 UI 中输入目标后自动创建任务并启动 Orchestrator。

运行流程

cf run "goal"
  -> Dashboard 在后台线程启动 (Web UI 监控)
  -> PlannerSession (CC Session) 将 goal 分解为 Feature 列表
     CC 探索代码库、多轮规划、写入 .cf/plan.json
  -> Plan Review: 用户在终端或 Dashboard 中审批/编辑/重规划
  -> Loop (每轮 = 一个 Claude Code 会话):
      1. CF 构建 session prompt (当前 Feature + 上下文 + 评估反馈)
      2. 以交互模式启动 Claude Code (pexpect PTY 保留完整 TUI)
      3. Idle Detection: 后台线程监控输出新颖度，空闲超时后自动发送 /exit
      4. CC 完成后退出 -> 控制权回到 CF
      5. ProgrammaticVerifier: 自动跑构建/测试，硬性失败直接跳过 LLM 评估
      6. AdversarySession (CC Session) 三层对抗评估:
         Layer 1: 客观数据 (build/test/lint)
         Layer 2: 验收标准逐条判定 (MET/NOT_MET)
         Layer 3: 四维评分 + 问题发现 + 边界测试
      7. Hard Gate 检查: 测试失败/构建失败/验收未达标 -> 强制 fix
      8. git commit 检查点
      9. 采集本轮指标 (耗时 + Token 用量)
     10. 评估反馈注入下一轮 prompt (scores, issues, verdict)
     11. 下一轮
  -> 任务完成后输出格式化运行报告 (总耗时 / Session 明细 / Token 分布)

Plan Review

规划完成后，CF 会暂停等待人工审批：

终端模式（cf run "goal"）：

[Enter/y] 批准并开始执行
[e N] 编辑第 N 个 Feature（描述、验收标准等）
[d N] 删除第 N 个 Feature
[r] 附加备注并请求重新规划

Dashboard 模式（cf run 无参数）：

在浏览器 UI 中查看 Feature 列表、编辑、删除、批准或重规划

使用 --auto-approve 跳过审批，规划完成后直接开始执行。

Dashboard

启动后自动打开 **http://localhost:7070**，提供：

Feature 列表与完成进度
实时 Session 事件日志（SSE）
Session 详情查看（prompt / eval_input / evaluation 全链路）
Plan Review 审批界面
暂停 / 继续 / 停止 / 强制重规划 / 跳过 Feature
向下一次会话发送备注（人工干预）
回滚到任意历史 Session（git reset）

Claude Code 的工作进度通过 pexpect PTY 流式输出到终端，Dashboard 负责进度监控和控制。

架构

Agent 角色

Agent	实现方式	职责
Planner	交互式 CC Session	探索代码库，将目标分解为 Feature 列表，写入 `.cf/plan.json`；支持动态重规划
Adversary	CC Session (`--print` + `--json-schema`)	三层对抗评估：客观数据 → 验收判定 → 质量评分 + 问题发现
Claude Code	交互式 pexpect PTY	前台运行，执行所有编码、测试、调试工作

核心设计：CF 不直接调用 LLM API。Planner 和 Adversary 都通过启动 CC Session 来完成决策，利用 Claude Code 的完整 Agent 能力（读文件、跑命令、推理），而非简单的 API 调用。

三层对抗评估

AdversarySession 实现三层评估机制：

层级	内容	数据来源
Layer 1: 客观数据	构建状态、测试通过率、类型错误、lint 违规	ProgrammaticVerifier + CC 执行
Layer 2: 验收判定	逐条判定验收标准 MET/NOT_MET，附带证据	CC 审查代码
Layer 3: 质量评估	四维评分（design/functionality/craft/originality）、问题发现、边界测试	CC 深度审查

评估结果通过 Pydantic 模型结构化：EvalResult、ObjectiveResults、CriterionVerdict、Discovery、QualityScores。

Hard Gate 机制：测试失败、构建失败、验收标准未达标、存在 blocking 级问题时，无论 CC 的 verdict 如何，都强制判定为 fix。

ProgrammaticVerifier

在 LLM 评估之前运行代码化验证，如果构建或测试失败，直接返回结果跳过 LLM 评估，节省 token 和时间。

支持的项目类型：

Python（pytest）
Node.js（npm test / jest）
Rust（cargo build / cargo test）
Go（go build / go test）

Executor

Executor	命令	模式
`ClaudeCodeExecutor`	`claude`	交互式 pexpect PTY
`GeminiExecutor`	`gemini`	前台交互

ClaudeCodeExecutor 特性：

pexpect PTY：保留完整 TUI 交互体验，用户可实时看到 Claude Code 的输出
内容新颖度检测：后台线程跟踪输出内容 hash，区分「真正的新输出」和「TUI 重绘」，只有新内容才重置空闲计时器
Gate File 模式：Planning Session 中，空闲检测在目标文件（如 plan.json）就绪后才激活
Token 采集：Session 结束后从 CC 会话日志（JSONL 文件）中解析 Token 用量数据

评估反馈传导

每轮评估的结果会结构化注入下一轮 Coder 的 session prompt：

反馈类型	注入方式
Hard Gate 失败	醒目标记，要求优先修复
四维评分	低于 3 分的维度标注警告
验收标准状态	逐条 MET/NOT_MET
Blocking Issues	必须修复的问题列表，附修复建议
Suggestions	质量改进建议

指标采集

CF 内置完整的指标采集系统，覆盖三个阶段：

阶段	采集内容
规划阶段	CC Planning Session 耗时 + Token 用量
执行阶段	Claude Code 执行耗时 + Token 用量（从会话日志解析）
评估阶段	CC Adversary Session 耗时 + Token 用量

任务完成后，CLI 输出格式化报告：目标、状态、总耗时、每个 Session 的明细、Token 分布统计。指标数据同时持久化到 task-state.json 的 metrics_data 字段。

会话间状态传递

基于 Anthropic 文章的最佳实践，CF 通过以下机制在会话间传递上下文：

机制	说明
`claude-progress.txt`	人类可读的进度日志，每个会话读+追加
`.cf/tasks/<id>/progress.json`	结构化 Feature 列表（JSON 格式，不易被模型误改）
`CLAUDE.md`	项目上下文 + 当前 Feature 信息，Claude Code 自动读取
`git log / git diff`	代码变更历史，最可靠的进度信号
`--append-system-prompt`	注入持久行为规则（不删测试、自验证、写进度等）
评估反馈	上一轮的 scores / issues / verdict 注入下一轮 prompt

会话 Prompt 设计

每个 Claude Code 会话的 prompt 遵循 先定位、再执行 原则：

pwd 确认工作目录
读 claude-progress.txt 了解之前做了什么
查 git log 看最近变更
检查现有功能是否正常（跑测试、看 dev server）
修复已有 bug（如果有），再开始新 Feature
实现当前 Feature，自验证通过后 commit
更新 claude-progress.txt 后退出

首次会话使用"初始化"prompt（侧重探索代码库），后续会话使用"编码"prompt（侧重继续进度）。当存在上一轮评估反馈时，会优先注入 Hard Gate 失败信息和 blocking issues。

容错机制

机制	说明
崩溃会话保护	CC 在 `CF_MIN_SESSION_SECONDS`（默认 10s）内退出且 exit code 非 0，跳过评估，标记 blocked
强制通过 + 构建检查	单个 Feature 重试超过 `CF_MAX_FEATURE_RETRIES`（默认 3）次，先检查项目是否能构建，能则强制 pass，不能则 blocked
无变更检测	连续 3 轮无 git diff 变更，自动标记 Feature 为 blocked
评估重试	JSON 提取失败时自动重试（`CF_EVAL_RETRIES`），支持 json5 宽松解析和括号修复
批量评估	`CF_EVAL_INTERVAL` 控制评估频率，减少评估开销

文件说明

文件	作用
`~/.claude-forever/.env`	全局配置文件（cf config 生成）
`.cf/tasks/<id>/task-state.json`	任务状态检查点，进程崩溃后可续跑
`.cf/tasks/<id>/progress.json`	结构化 Feature 列表
`.cf/plan.json`	Planner CC Session 的规划输出
`.cf/eval.json`	Adversary CC Session 的评估输出
`claude-progress.txt`	人类可读的会话进度日志
`control.json`	进程间控制信号（pause/stop）
`CLAUDE.md`	项目上下文 + CF 会话信息（会话结束后自动恢复原始内容）

环境变量

变量	默认值	说明
`CF_EXECUTOR`	`claude`	前台运行的编码 CLI
`CF_CONTROL_FILE`	`control.json`	控制文件路径
`CF_DASHBOARD_PORT`	`7070`	Dashboard 端口
`CF_DASHBOARD_HOST`	`127.0.0.1`	Dashboard 绑定地址
`CF_WECOM_WEBHOOK`	--	企业微信通知 Webhook
`CF_IDLE_TIMEOUT`	`30`	Claude Code 空闲检测超时（秒）
`CF_STREAM_EXECUTOR`	`1`	是否流式输出 Executor stdout/stderr
`CF_DIR`	`.cf`	CF 数据目录
`CF_DEBUG`	--	设为 `1` 启用详细日志
`CF_DEBUG_IDLE`	--	设为 `1` 启用空闲检测调试日志
`CF_EVAL_INTERVAL`	`1`	评估频率（1=每个 Feature 评估，0=全部完成后评估，N=每 N 个评估）
`CF_MAX_FEATURE_RETRIES`	`3`	单个 Feature 最大重试次数，超过后强制 pass 或 blocked
`CF_MIN_SESSION_SECONDS`	`10`	CC 最短会话时间，低于此值视为崩溃
`CF_ADVERSARY_TIMEOUT`	`600`	Adversary CC Session 超时（秒）
`CF_EVAL_RETRIES`	`1`	评估 JSON 提取失败时的重试次数
`CF_PLAN_GATE_GRACE`	`15`	Planning Session 中 gate file 就绪后的等待时间（秒）

设计动机

为什么从 Controller 重构为 Harness？

旧架构的三个核心问题：

三层中间 Agent（Coder/Tester/Reviewer）冗余 -- Claude Code 本身就能做所有这些事
stdout/stderr 被 PIPE 捕获，Claude Code 的输出被完全吞掉，用户看不到工作过程
过度控制 -- CF 替 Claude Code 做决策，而不是让它自主工作

新架构的核心转变：CF 从「替 Claude Code 做决策」变为「为 Claude Code 搭脚手架」-- 管理状态、做检查点、评估进度，让 Claude Code 以完整能力自主工作。

为什么 Planner/Adversary 也用 CC Session？

旧方案通过 LiteLLM 直接调用 LLM API（Planner 和 Evaluator 各自构造 prompt + 调 API）。改为 CC Session 后：

更强的能力 -- CC Session 可以读文件、跑命令、多轮推理，比纯 API 调用获得更多上下文
零配置 -- 不再需要用户配置 LLM 模型、API Key、代理地址，CC 本身的认证链自动生效
ECC 技能加持 -- Planner 可以用 /plan 技能，Adversary 可以用 /verify 技能
结构化输出 -- 通过 --json-schema 让 CC API 层面强制输出合法 JSON，比解析文本可靠得多

为什么不用 Stop Hook？

我们实际尝试过 Claude Code 的 Stop Hook 机制（在 CC 完成 response 时触发 hook 输出 {"continue": false}），但实测发现两个根本问题：

{"continue": false} 不会导致进程退出 -- 它只是停止当前 response，CC 进程仍然存活在空闲态等待输入
context 线性增长 -- 如果通过 {"decision": "block"} 强制 CC 继续（让它在同一进程内多轮工作），约第 15 轮就会耗尽 200k 上限，且无法从 Hook 内部重置

claude-forever 的设计完全绕开这两个问题 -- 每个会话是全新进程（CC 完成后自动退出），context 保持在合理范围，可以稳定跑 50、100 甚至 500 轮。会话间通过 claude-progress.txt + git 历史传递上下文。

开源版本

本项目的开源版本托管在 GitHub：

仓库地址：https://github.com/wBeacon/claude-forever
安装方式：pipx install git+https://github.com/wBeacon/claude-forever.git

GitHub 仓库是本项目的公开发布来源。

Name		Name	Last commit message	Last commit date
claude_forever		claude_forever
docs		docs
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README-EN.md		README-EN.md
README.md		README.md
install.sh		install.sh
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Navigation Menu

Repository files navigation

claude-forever

核心理念

安装

前置要求

配置

使用

运行流程

Plan Review

Dashboard

架构

Agent 角色

三层对抗评估

ProgrammaticVerifier

Executor

评估反馈传导

指标采集

会话间状态传递

会话 Prompt 设计

容错机制

文件说明

环境变量

设计动机

为什么从 Controller 重构为 Harness？

为什么 Planner/Adversary 也用 CC Session？

为什么不用 Stop Hook？

开源版本

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

claude-forever

核心理念

安装

前置要求

配置

使用

运行流程

Plan Review

Dashboard

架构

Agent 角色

三层对抗评估

ProgrammaticVerifier

Executor

评估反馈传导

指标采集

会话间状态传递

会话 Prompt 设计

容错机制

文件说明

环境变量

设计动机

为什么从 Controller 重构为 Harness？

为什么 Planner/Adversary 也用 CC Session？

为什么不用 Stop Hook？

开源版本

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages