Ralph for Claude Code
让 Claude Code 在带退出保护与限流的循环中持续完成开发任务。
- Star 数
- ★ 9.7k
- 最近更新
- 2 天前
- License
- MIT
- 主语言
- Shell
- FA 评分
- 53/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 平台专用Claude Code
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 使用 Claude Code 的独立开发者，希望让工具围绕
.ralph/fix_plan.md持续实现和验证一组已排序的功能任务。 - 不适合
- 依赖 Claude Code 之外其他编码代理的团队，多提供商支持仍在开发中
- 无法安装 Bash、jq、Git 和 Claude Code CLI 的环境
- 不愿让代码或议题内容发送到云端模型的组织
- 源码审查
- 53/100 · 缺口较多
这个 Agent 能做什么，适合哪些场景？
Ralph 是面向 Claude Code 的命令行自主开发循环工具，以全局安装命令和项目内 .ralph/ 配置目录运行。它读取 .ralph/PROMPT.md、fix_plan.md 和可选规格文件，反复调用 Claude Code，并记录状态、日志、会话和指标。其退出机制要求完成度指标与 EXIT_SIGNAL: true 同时满足，另配有限流、熔断器、超时与 API 限额处理，旨在避免无效或过早停止的循环。项目可通过 ralph-enable、ralph-setup 或 ralph-import 初始化，也可从 GitHub Issue 建立任务。它可在主机上运行 Claude Code，或将 Claude 的执行部分放进 Docker 或 E2B 沙箱；当前核心仍依赖 Claude Code，而多提供商抽象处于进行中状态。
执行 ralph 时，Ralph 加载项目提示和优先级任务，调用配置的 CLAUDE_CODE_CMD（默认 claude），并在每轮后解析 JSON 或文本输出。它把 Claude 会话状态保存到 .ralph/.ralph_session，将日志写入 .ralph/logs/，并可通过 ralph --status 输出状态、通过 ralph-stats 汇总 JSON Lines 指标。ralph-enable 会检测项目类型并生成 .ralph/、.ralphrc 等文件；ralph-import 可从本地需求文档或 GitHub Issue 生成 PROMPT.md、fix_plan.md 和规格文件。ralph-queue 将 Issue 或本地 PRD 保存在 .ralph/queue.json，按优先级和依赖顺序逐项处理。可选的 --monitor 使用 tmux 展示监控面板，--sandbox docker 或 --sandbox e2b 将 Claude Code 的执行放入相应沙箱。
- 使用 Claude Code 的独立开发者，希望让工具围绕
.ralph/fix_plan.md持续实现和验证一组已排序的功能任务。 - 维护已有 TypeScript、Python、Rust 或 Go 项目的团队，需要通过
ralph-enable在现有仓库中生成 Ralph 配置并导入任务来源。 - 将产品需求、技术规格或 PDF 转为可执行开发计划的工程师，可使用
ralph-import创建项目结构和优先级任务。 - 以 GitHub Issue 管理待办的仓库维护者，需要按标签、里程碑、负责人或标题筛选 Issue，并串联评论、建 PR、关闭 Issue 等生命周期操作。
- 需要隔离 Claude Code 文件修改和命令执行的团队，可在 Docker 容器或 E2B 云沙箱中运行循环。
- 需要按优先级与依赖关系串行处理多个 Issue 或需求文档的开发负责人，可使用持久化的
ralph-queue。
如何安装或部署这个 Agent？
前置条件包括 Bash 4.0+、Claude Code CLI、jq、Git 与 GNU coreutils 的 timeout 命令；macOS 上 README 指定通过 brew install coreutils 获得 gtimeout。安装 Claude Code CLI 的示例是 npm install -g @anthropic-ai/claude-code。随后运行：
git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code
./install.sh这会将 ralph、ralph-monitor、ralph-setup、ralph-import、ralph-queue、ralph-migrate、ralph-enable 和 ralph-enable-ci 加入 PATH。常规运行依赖可用的 Claude Code CLI；README 未给出其常规认证步骤。Docker 模式可使用 ANTHROPIC_API_KEY 或主机的 ~/.claude/.credentials.json，E2B 模式需要 pip install e2b 并设置 E2B_API_KEY。
如何使用这个 Agent？
在现有项目中执行：
cd my-existing-project
ralph-enable
ralph --monitor若从需求文档开始，可执行 ralph-import product-requirements.md my-app，进入生成目录后运行 ralph --monitor。如需非交互式初始化，可用 ralph-enable-ci --from github --json。在项目 .ralphrc 中可设置 CLAUDE_CODE_CMD="claude"、MAX_CALLS_PER_HOUR=100、CLAUDE_TIMEOUT_MINUTES=15、ALLOWED_TOOLS 和会话参数；首次运行的默认提示文件为 .ralph/PROMPT.md。需要隔离执行时可用 ralph --sandbox docker 或 ralph --sandbox e2b。
这个 Agent 有哪些优点和局限？
- 双条件退出门同时检查完成度指标和 Claude 明确的
EXIT_SIGNAL，降低仅凭自然语言“完成”判断而提前退出的风险。 - 内置每小时调用与令牌限制、API 5 小时限制处理、熔断器和会话过期机制，针对长时间无人值守循环提供控制点。
- 覆盖从需求或 GitHub Issue 导入、任务队列、循环执行到可选 PR 创建和 Issue 关闭的开发工作流。
- Docker 与 E2B 两种沙箱模式将 Claude 执行与宿主循环分开，Docker 可保留循环间容器状态，E2B 提供文件同步与成本上限参数。
- 提供
ralph-enable、ralph-enable-ci、.ralphrc、tmux 监控、实时输出、日志轮转、指标和备份/回滚等面向 CLI 工作流的操作功能。
- 核心执行依赖 Claude Code CLI；README 中的多提供商代理抽象仍标记为进行中，不能据此视为当前跨模型工具。
- 需要 Bash、jq、Git、GNU coreutils 和 Claude Code CLI；使用集成监控还需要 tmux，macOS 需额外处理
gtimeout。 - 自动编辑文件和运行命令的权限由
ALLOWED_TOOLS控制，权限不足会使 Ralph 停止，采用前需要为项目设定合适的工具许可。 - GitHub Issue 导入和生命周期操作依赖已安装并认证的
gh，且使用 Issue 评论导入时需要自行判断评论内容是否可信。 - E2B 同步会将沙箱中删除或重命名的文件传播到主机，且沙箱内 Git 提交不会同步回主机；Docker/E2B 也增加了环境与凭据管理成本。
这个 Agent 与同类方案有什么区别？
README 将 Aider 列为与 Ralph 技术相关的项目，并说明 Ralph 的灵感来自 Geoffrey Huntley 提出的 Ralph technique。Ralph 的文档明确将当前实现定位为 Claude Code 的开发循环；未提供与 Aider 的逐项功能对比。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Ralph for Claude Code 当前 | 53 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 9.7k | 2 天前 | Shell | Claude Code |
| Forgeo 软件工厂 | 76 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 35 | 5 天前 | Python | Codex · Claude Code |
| mini-swe-agent | 54 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 9.1k | 3 天前 | Python | — |
| Pilot | 53 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 727 | 今天 | Go | Claude Code |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示：README 描述了 --allowed-tools 限制工具权限、--dry-run 模拟、--backup/--rollback 备份恢复、--include-comments 默认排除评论等安全特性；GitHub Actions 工作流使用最小权限和只读 checkout。扣分：未提供实际代码验证权限实现，依赖安全仅提及固定版本 actions，未提供依赖审计；数据流透明度仅描述功能，未展示实际日志内容；敏感数据处理未明确说明。
证据显示：README 和测试文件展示了错误检测、卡死检测等逻辑，测试文件包含具体测试用例，自洽性较好。扣分：依赖可用性仅提及 bats 等，未提供完整依赖清单；失败消息在测试中有体现，但未覆盖所有场景。
证据显示：README 描述了多种使用场景（新项目、现有项目、PRD 导入、GitHub Issues），支持多种项目类型和框架，提供 ralph-enable 向导和配置选项。扣分：能力边界未明确说明，触发精度依赖 Claude 输出，环境适配未覆盖所有平台。
证据显示：README 结构清晰，包含安装、使用、配置、故障排除等章节；提供 install.sh 和 uninstall.sh；版本号在 README 和 package.json 中不一致（README 0.11.5，package.json 1.0.0）；有 changelog 但未独立文件；已知限制未明确列出。
证据显示：README 描述了输出格式（JSON、文本）、实时流、日志轮转等，输出可用性较好；边际价值体现在自动化循环和智能退出检测；成本效益未提供实际数据，仅声称 784 测试通过。
证据显示：README 声称 784 测试通过，但未提供测试报告链接；测试文件存在，但未提供独立验证；事实与推断未明确区分。
- 版本号不一致：README 显示 0.11.5，package.json 显示 1.0.0，可能引起混淆。
- 依赖安全未提供审计，仅固定了 actions 版本，建议检查依赖漏洞。
- 敏感数据处理未明确说明，特别是涉及 GitHub token 和 API 密钥时需谨慎。
- 测试声称 784 通过，但未提供可复现的测试报告，建议独立验证。
常见问题
Ralph 何时会停止循环？
completion_indicators >= 2 且 EXIT_SIGNAL: true。它也会检查任务完成状态、连续完成信号、测试型循环和 API 5 小时使用限制等条件。它会直接调用 Anthropic API 吗？
ANTHROPIC_API_KEY 传入沙箱，或复制主机的 Claude 凭据文件；README 未说明 Ralph 自身提供独立的通用 Anthropic API 客户端。如何限制成本或避免循环失控？
MAX_CALLS_PER_HOUR 和可选的 MAX_TOKENS_PER_HOUR，并使用超时、熔断器、冷却期、--dry-run 以及 E2B 的 --sandbox-max-cost 等参数。能否从 GitHub Issue 开始并自动收尾？
ralph-import --github-issue 可将 Issue 转为 Ralph 项目；运行循环时可结合 --comment-progress、--create-pr、--link-issue、--close-summary 和 --auto-close，但这些操作要求 gh 已认证。Docker 和 E2B 的隔离边界有什么不同？
.git，因此其内部提交不会成为主机提交。