Ralph for Claude Code

具备智能退出检测和速率限制的 AI 自主开发循环

Ralph 实现了 Geoffrey Huntley 为 Claude Code 提出的技术方案，该方案以 Ralph Wiggum 命名，旨在实现持续的自主开发循环。它允许 Claude Code 迭代地改进你的项目直至完成，并内置了防止无限循环和 API 过度使用的安全机制。

一次安装，随处使用 - Ralph 成为一个可在任何目录下使用的全局命令。

项目状态

版本: v0.11.5 - 开发中 核心功能: 已完成并经过测试 测试覆盖率: 566 个测试，通过率 100%

当前可用功能

• 具备智能退出检测的自主开发循环
• 双重条件退出门控: 要求同时满足“完成指标”和明确的“EXIT_SIGNAL”
• 速率限制与每小时重置功能（默认 100 次调用/小时，可配置）
• 带有高级错误检测的熔断机制（防止失控循环）
• 具备语义理解和两阶段错误过滤的响应分析器
• 支持 JSON 输出格式，并自动回退至文本解析
• 通过 --resume 标志保持会话连续性（无会话劫持）
• 具有可配置超时的会话过期机制（默认：24 小时）
• 现代 CLI 标志: --output-format, --allowed-tools, --no-continue
• 通过 ralph-enable 向导进行交互式项目启用
• 用于项目设置的 .ralphrc 配置文件
• 通过 --live 标志实现实时流式输出，以便实时查看 Claude Code 动态
• 多行错误匹配，实现精准的死循环检测
• 5 小时 API 限制处理（带有用户提示）
• tmux 集成，用于实时监控
• PRD 导入功能
• 采用 GitHub Actions 的 CI/CD 流水线
• 专用的卸载脚本，实现彻底清除

近期改进

v0.11.5 - 社区 Bug 修复（最新版）

• 修复 API 限制误报：超时（退出代码 124）不再被错误识别为 API 5 小时限制 (#183)
• 三层 API 限制检测：超时防护 → 结构化 JSON (rate_limit_event) → 过滤后的文本回退
• 无人值守模式：API 限制提示现在会在超时时自动等待，而不是直接退出
• 修复 Bash 3.x 兼容性：将 ${,,} 小写转换替换为 POSIX tr (#187)
• 新增 8 个 API 限制检测测试（测试总数从 548 增加到 566）

v0.11.4 - Bug 修复与兼容性

• 修复进度检测：循环内的 Git 提交现在计入进度 (#141)
• 修复复选框正则表达式：日期条目 [2026-01-29] 不再被计为复选框 (#144)
• 修复会话劫持：使用 --resume 代替 --continue (#151)
• 修复 EXIT_SIGNAL 覆盖逻辑：STATUS: COMPLETE 配合 EXIT_SIGNAL: false 现在会继续执行任务 (#146)
• 修复 ralph-import 挂起问题（添加了非交互模式下的 --print 标志）
• 修复 ralph-import 的绝对路径处理
• 修复 macOS 下使用 Homebrew coreutils 的跨平台日期命令问题
• 通过环境变量增加可配置的熔断阈值 (#99)
• 为非零 base-index 配置增加了 tmux 支持
• 新增 13 个针对进度检测和复选框正则表达式的回归测试

v0.11.3 - 实时流与 Beads 修复

• 添加了带有 --live 标志的实时流输出模式，用于实时监控 Claude Code (#125)
• 修复了使用正确 bd list 参数的 Beads 任务导入问题 (#150)
• 应用了 CodeRabbit 审查修复：camelCase 变量、尊重状态的回退逻辑、jq 防护
• 新增 12 个针对实时流和 Beads 导入的测试

v0.11.2 - 安装权限修复

• 修复 #136 问题：ralph-setup 现在创建具有一致工具权限的 .ralphrc
• 更新默认 ALLOWED_TOOLS 以包含 Edit, Bash(npm *) 和 Bash(pytest)
• ralph-setup 和 ralph-enable 现在均创建相同的 .ralphrc 配置
• 监控程序现在将所有 CLI 参数转发给内部的 Ralph 循环 (#126)
• 新增 16 个针对权限和参数转发的测试

v0.11.1 - 完成指标修复

• 修复在 JSON 输出模式下循环 5 次后过早退出的问题
• completion_indicators 现在仅在 EXIT_SIGNAL: true 时累加