frankbria / ralph-claude-code

frankbria/ralph-claude-code

open_in_new前往仓库

为Claude Code设计的自主AI开发循环，具备智能退出检测功能。

项目概览

项目概述

Ralph for Claude Code 是一个基于 Shell 脚本的自主 AI 开发循环工具，旨在为 Claude Code CLI 提供持续、自主的开发迭代能力。它实现了 Geoffrey Huntley 提出的 Ralph 技术，通过智能退出检测和速率限制，让 Claude Code 能够迭代改进项目直至完成，同时避免无限循环和 API 过度使用。项目当前版本为 v0.11.5，处于积极开发阶段，拥有 784 个测试且全部通过。

核心功能

  • 自主开发循环：持续执行 Claude Code，根据项目需求迭代开发。
  • 智能退出检测：采用双条件退出门控，要求同时满足完成指标和显式 EXIT_SIGNAL。
  • 会话连续性：跨循环迭代保留上下文，支持会话过期和自动重置。
  • 速率限制与熔断器：内置 API 调用管理（默认每小时 100 次），熔断器防止停滞循环。
  • 实时监控：通过 tmux 集成提供实时仪表盘，显示循环状态、进度和日志。
  • 任务管理：基于优先级的任务列表和进度跟踪。
  • 项目模板与交互式设置：ralph-enable 向导自动检测项目类型并导入任务。
  • 配置灵活：支持 .ralphrc 配置文件、自定义提示词、超时设置等。
  • 沙箱执行：支持 Docker 和 E2B 云沙箱，隔离 Claude 执行环境。
  • GitHub 集成：支持从 GitHub Issues 导入任务，并可自动创建 PR、关闭 Issue。
  • 批处理队列：ralph-queue 支持批量处理多个 Issue 或 PRD。
  • 丰富的 CLI 选项：包括 --live 实时输出、--dry-run 模拟运行、--backup 备份等。

适用与不适用场景

适用场景：

  • 需要长时间自主运行的开发任务，如从 PRD 生成完整项目。
  • 希望减少人工干预的迭代开发流程。
  • 需要批量处理多个 GitHub Issue 或规格文档的场景。
  • 希望在隔离环境中运行 AI 编码代理以增强安全性的场景。

不适用场景：

  • 需要严格人工审查每一步的敏感项目。
  • 对 API 成本极其敏感，无法容忍自主循环消耗大量 token 的场景。
  • 需要实时交互式编程，而非自主循环的场景。
  • 项目依赖复杂的外部服务，且无法在沙箱中复现的场景。

技术架构与依赖

Ralph 主要由 Shell 脚本（Bash）实现，核心组件包括：

  • ralph_loop.sh：主循环脚本，负责执行 Claude Code、分析响应、更新状态。
  • lib/response_analyzer.sh：响应分析器，解析 Claude 输出，检测完成信号。
  • lib/circuit_breaker.sh：熔断器，防止停滞循环。
  • lib/sandbox_docker.sh 和 lib/e2b_helper.py：沙箱执行支持。
  • ralph_monitor.sh：监控仪表盘。
  • ralph_import.sh、ralph_enable.sh 等辅助工具。

主要依赖：

  • Bash 4.0+、Claude Code CLI、tmux（推荐）、jq、Git、GNU coreutils（macOS 需要）。
  • 可选：Docker（沙箱）、E2B Python SDK（云沙箱）、GitHub CLI（Issue 集成）。

安装与快速开始

安装（一次性）：

git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code
./install.sh

项目初始化（每个项目）：

# 在现有项目中启用（推荐）
cd my-existing-project
ralph-enable

# 或从 PRD 导入
ralph-import my-requirements.md my-project

# 或创建新项目
ralph-setup my-awesome-project

启动开发循环：

ralph --monitor

典型使用方法

基本用法：

ralph --monitor              # 集成 tmux 监控
ralph --calls 50             # 限制每小时 API 调用次数
ralph --timeout 30           # 设置执行超时（分钟）
ralph --live                 # 实时流式输出
ralph --dry-run              # 模拟运行，不调用 API

从 GitHub Issues 导入：

ralph-import --github-issue 42
ralph-import --github-label "bug,P0" --select priority

批处理队列：

ralph-queue add --github-label "bug,P0"
ralph --process-queue

沙箱执行：

ralph --sandbox docker
ralph --sandbox e2b --sandbox-max-cost 5.00

配置与部署要点

配置文件 .ralphrc：

  • 设置项目名称、类型、速率限制、工具权限、会话管理等。
  • 环境变量优先级高于 .ralphrc。

关键配置项：

  • MAX_CALLS_PER_HOUR：每小时最大调用次数（默认 100）。
  • CLAUDE_TIMEOUT_MINUTES：单次执行超时（默认 15）。
  • ALLOWED_TOOLS：允许的工具列表，默认包含特定 git 子命令和 npm/pytest。
  • SESSION_CONTINUITY：会话连续性开关。
  • CB_NO_PROGRESS_THRESHOLD：熔断器无进展阈值。

部署要点：

  • 确保所有依赖已安装（Claude Code CLI、tmux、jq 等）。
  • 对于无人值守运行，建议设置 CB_AUTO_RESET=true 和适当的速率限制。
  • 沙箱执行时，确保 Docker 或 E2B 环境正确配置。

限制、风险与许可证

限制：

  • 依赖 Claude Code CLI，其可用性和行为可能变化。
  • 自主循环可能消耗大量 API token，需谨慎设置速率限制。
  • 沙箱同步（E2B）不支持沙箱内提交的同步。
  • 多提供商支持（如 Codex、Gemini）仍在规划中，当前仅支持 Claude。

风险：

  • 自主代理可能执行意外操作，建议使用沙箱和工具权限限制。
  • GitHub Issue 内容被视为不可信输入，需注意提示注入风险。
  • 熔断器可能误判，导致提前退出或过度等待。

许可证： MIT License。

官方链接

信息来源和分析时间

  • 信息来源：GitHub 仓库 README、文档（docs/ 目录）、CONTRIBUTING.md。
  • 分析时间：2026-06-15（基于仓库内容中的日期）。