frankbria/ralph-claude-code

它解决的问题

Ralph 解决了将单个 Claude Code 调用转变为完整、无人值守的开发周期的问题。Ralph 不是手动反复提示 Claude，而是循环运行 Claude Code，读取项目指令、执行代码更改、跟踪进度，并重复直到项目真正完成。它还防止了此类循环的两种常见故障模式：因为错误读取退出信号而永远运行，以及耗尽每小时或 5 小时的 API 限制。

工作原理

Ralph 运行一个循环：从 .ralph/PROMPT.md 加载项目指令，使用当前上下文执行 Claude Code，然后更新任务列表和日志。它使用双条件门检查完成情况：完成指示符的启发式计数（自然语言模式中至少 2 个）和 Claude 输出中明确的 EXIT_SIGNAL: true 必须同时存在。如果任一缺失，循环继续。Ralph 还使用断路器，在连续多个完成信号后强制退出，使用每小时上限（默认 100 次调用）的速率限制，具有三层检测的 5 小时 API 限制检测器，以及使用 --resume 进行上下文保留的会话管理。它可以使用 --live 流式传输实时输出，在 Docker 或 E2B 沙箱中运行，并自动备份 git 状态。

适用人群

Ralph 适用于使用 Claude Code 并希望将较长的多步骤编码任务委托给自主代理循环的开发人员。它对于将产品需求文档（PRD）或 GitHub 问题转化为可工作的代码库特别有用，只需最少的手动提示。它也适合需要在明确定义的任务列表上取得无人值守进展的团队。

亮点

• 双条件退出检测（完成指示符 + 明确的 EXIT_SIGNAL）以避免过早或无限循环。
• 具有每小时重置的速率限制和断路器，以防止 API 过度使用和失控循环。
• 使用 --resume 的会话连续性（无会话劫持）和可配置的会话过期时间（默认 24 小时）。
• 5 小时 API 限制的三层检测，包括超时保护、JSON 解析和文本回退。
• 交互式 ralph-enable 向导，自动检测项目类型并从 beads、GitHub Issues 或 PRD 导入任务。
• ralph-import 将 markdown、文本、JSON、DOCX 和 PDF 需求文档转换为结构化的 Ralph 项目。
• Docker 和 E2B 云沙箱执行，具有资源限制和成本跟踪。
• 可选的实时流式传输、桌面通知、试运行模式和自动 git 备份分支，支持回滚。