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 导入功能
• CI/CD 流水线: 使用 GitHub Actions
• 专用卸载脚本: 确保彻底清理

近期改进

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 时累加