[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-frankbria--ralph-claude-code":3,"tool-frankbria--ralph-claude-code":62},[4,18,26,36,46,54],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",159267,2,"2026-04-17T11:29:14",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":42,"last_commit_at":43,"category_tags":44,"status":17},8272,"opencode","anomalyco\u002Fopencode","OpenCode 是一款开源的 AI 编程助手（Coding Agent），旨在像一位智能搭档一样融入您的开发流程。它不仅仅是一个代码补全插件，而是一个能够理解项目上下文、自主规划任务并执行复杂编码操作的智能体。无论是生成全新功能、重构现有代码，还是排查难以定位的 Bug，OpenCode 都能通过自然语言交互高效完成，显著减少开发者在重复性劳动和上下文切换上的时间消耗。\n\n这款工具专为软件开发者、工程师及技术研究人员设计，特别适合希望利用大模型能力来提升编码效率、加速原型开发或处理遗留代码维护的专业人群。其核心亮点在于完全开源的架构，这意味着用户可以审查代码逻辑、自定义行为策略，甚至私有化部署以保障数据安全，彻底打破了传统闭源 AI 助手的“黑盒”限制。\n\n在技术体验上，OpenCode 提供了灵活的终端界面（Terminal UI）和正在测试中的桌面应用程序，支持 macOS、Windows 及 Linux 全平台。它兼容多种包管理工具，安装便捷，并能无缝集成到现有的开发环境中。无论您是追求极致控制权的资深极客，还是渴望提升产出的独立开发者，OpenCode 都提供了一个透明、可信",144296,1,"2026-04-16T14:50:03",[13,45],"插件",{"id":47,"name":48,"github_repo":49,"description_zh":50,"stars":51,"difficulty_score":32,"last_commit_at":52,"category_tags":53,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[14,15,13],{"id":55,"name":56,"github_repo":57,"description_zh":58,"stars":59,"difficulty_score":32,"last_commit_at":60,"category_tags":61,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[45,13,15,14],{"id":63,"github_repo":64,"name":65,"description_en":66,"description_zh":67,"ai_summary_zh":67,"readme_en":68,"readme_zh":69,"quickstart_zh":70,"use_case_zh":71,"hero_image_url":72,"owner_login":73,"owner_name":74,"owner_avatar_url":75,"owner_bio":76,"owner_company":77,"owner_location":78,"owner_email":79,"owner_twitter":77,"owner_website":80,"owner_url":81,"languages":82,"stars":87,"forks":88,"last_commit_at":89,"license":90,"difficulty_score":32,"env_os":91,"env_gpu":92,"env_ram":92,"env_deps":93,"category_tags":101,"github_topics":102,"view_count":32,"oss_zip_url":77,"oss_zip_packed_at":77,"status":17,"created_at":112,"updated_at":113,"faqs":114,"releases":143},8579,"frankbria\u002Fralph-claude-code","ralph-claude-code","Autonomous AI development loop for Claude Code with intelligent exit detection","Ralph 是一款专为 Claude Code 设计的自动化开发辅助工具，旨在实现智能且安全的持续代码迭代。它基于 Geoffrey Huntley 提出的\"Ralph\"理念，让 AI 能够自主循环执行开发任务，直到项目完成或达到预设目标，从而将开发者从重复的指令输入中解放出来。\n\n该工具核心解决了自主代理运行中常见的“死循环”与\"API 过度消耗”难题。通过独特的双重退出机制，Ralph 要求同时满足“任务完成指标”与“明确退出信号”才会停止运行，有效防止了无限循环。此外，它还内置了速率限制、熔断保护以及复杂的错误检测系统，确保在遇到 API 限额或逻辑卡顿时能安全暂停而非崩溃。\n\nRalph 非常适合希望提升开发效率的软件工程师、技术团队及 AI 应用研究者使用。其技术亮点包括支持会话断点续传（`--resume`）、实时流式输出监控、灵活的 JSON\u002F文本格式切换，以及基于 `.ralphrc` 的项目级配置管理。安装一次后，它即可作为全局命令在任何目录中运行，配合完善的测试覆盖与 CI\u002FCD 集成，为自动化编码流程提供了稳定可靠的保障。","# Ralph for Claude Code\n\n[![CI](https:\u002F\u002Fgithub.com\u002Ffrankbria\u002Fralph-claude-code\u002Factions\u002Fworkflows\u002Ftest.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Ffrankbria\u002Fralph-claude-code\u002Factions\u002Fworkflows\u002Ftest.yml)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-blue.svg)](LICENSE)\n![Version](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fversion-0.11.5-blue)\n![Tests](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Ftests-556%20passing-green)\n[![GitHub Issues](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fissues\u002Ffrankbria\u002Fralph-claude-code)](https:\u002F\u002Fgithub.com\u002Ffrankbria\u002Fralph-claude-code\u002Fissues)\n[![Mentioned in Awesome Claude Code](https:\u002F\u002Fawesome.re\u002Fmentioned-badge.svg)](https:\u002F\u002Fgithub.com\u002Fhesreallyhim\u002Fawesome-claude-code)\n[![Follow on X](https:\u002F\u002Fimg.shields.io\u002Ftwitter\u002Ffollow\u002FFrankBria18044?style=social)](https:\u002F\u002Fx.com\u002FFrankBria18044)\n\n> **Autonomous AI development loop with intelligent exit detection and rate limiting**\n\nRalph is an implementation of the Geoffrey Huntley's technique for Claude Code that enables continuous autonomous development cycles he named after [Ralph Wiggum](https:\u002F\u002Fghuntley.com\u002Fralph\u002F). It enables continuous autonomous development cycles where Claude Code iteratively improves your project until completion, with built-in safeguards to prevent infinite loops and API overuse.\n\n**Install once, use everywhere** - Ralph becomes a global command available in any directory.\n\n## Project Status\n\n**Version**: v0.11.5 - Active Development\n**Core Features**: Working and tested\n**Test Coverage**: 566 tests, 100% pass rate\n\n### What's Working Now\n- Autonomous development loops with intelligent exit detection\n- **Dual-condition exit gate**: Requires BOTH completion indicators AND explicit EXIT_SIGNAL\n- Rate limiting with hourly reset (100 calls\u002Fhour, configurable)\n- Circuit breaker with advanced error detection (prevents runaway loops)\n- Response analyzer with semantic understanding and two-stage error filtering\n- **JSON output format support with automatic fallback to text parsing**\n- **Session continuity with `--resume` flag for context preservation (no session hijacking)**\n- **Session expiration with configurable timeout (default: 24 hours)**\n- **Modern CLI flags: `--output-format`, `--allowed-tools`, `--no-continue`**\n- **Interactive project enablement with `ralph-enable` wizard**\n- **`.ralphrc` configuration file for project settings**\n- **Live streaming output with `--live` flag for real-time Claude Code visibility**\n- Multi-line error matching for accurate stuck loop detection\n- 5-hour API limit handling with user prompts\n- tmux integration for live monitoring\n- PRD import functionality\n- **CI\u002FCD pipeline with GitHub Actions**\n- **Dedicated uninstall script for clean removal**\n\n### Recent Improvements\n\n**v0.11.5 - Community Bug Fixes** (latest)\n- Fixed API limit false positive: Timeout (exit code 124) no longer misidentified as API 5-hour limit (#183)\n- Three-layer API limit detection: timeout guard → structural JSON (`rate_limit_event`) → filtered text fallback\n- Unattended mode: API limit prompt now auto-waits on timeout instead of exiting\n- Fixed bash 3.x compatibility: `${,,}` lowercase substitution replaced with POSIX `tr` (#187)\n- Added 8 new tests for API limit detection (548 → 566 tests)\n\n**v0.11.4 - Bug Fixes & Compatibility**\n- Fixed progress detection: Git commits within a loop now count as progress (#141)\n- Fixed checkbox regex: Date entries `[2026-01-29]` no longer counted as checkboxes (#144)\n- Fixed session hijacking: Use `--resume \u003Csession_id>` instead of `--continue` (#151)\n- Fixed EXIT_SIGNAL override: `STATUS: COMPLETE` with `EXIT_SIGNAL: false` now continues working (#146)\n- Fixed ralph-import hanging indefinitely (added `--print` flag for non-interactive mode)\n- Fixed ralph-import absolute path handling\n- Fixed cross-platform date commands for macOS with Homebrew coreutils\n- Added configurable circuit breaker thresholds via environment variables (#99)\n- Added tmux support for non-zero `base-index` configurations\n- Added 13 new regression tests for progress detection and checkbox regex\n\n**v0.11.3 - Live Streaming & Beads Fix**\n- Added live streaming output mode with `--live` flag for real-time Claude Code visibility (#125)\n- Fixed beads task import using correct `bd list` arguments (#150)\n- Applied CodeRabbit review fixes: camelCase variables, status-respecting fallback, jq guards\n- Added 12 new tests for live streaming and beads import improvements\n\n**v0.11.2 - Setup Permissions Fix**\n- Fixed issue #136: `ralph-setup` now creates `.ralphrc` with consistent tool permissions\n- Updated default `ALLOWED_TOOLS` to include `Edit`, `Bash(npm *)`, and `Bash(pytest)`\n- Both `ralph-setup` and `ralph-enable` now create identical `.ralphrc` configurations\n- Monitor now forwards all CLI parameters to inner ralph loop (#126)\n- Added 16 new tests for permissions and parameter forwarding\n\n**v0.11.1 - Completion Indicators Fix**\n- Fixed premature exit after exactly 5 loops in JSON output mode\n- `completion_indicators` now only accumulates when `EXIT_SIGNAL: true`\n- Aligns with documented dual-condition exit gate behavior\n\n**v0.11.0 - Ralph Enable Wizard**\n- Added `ralph-enable` interactive wizard for enabling Ralph in existing projects\n- 5-phase wizard: Environment Detection → Task Source Selection → Configuration → File Generation → Verification\n- Auto-detects project type (TypeScript, Python, Rust, Go) and framework (Next.js, FastAPI, Django)\n- Imports tasks from beads, GitHub Issues, or PRD documents\n- Added `ralph-enable-ci` non-interactive version for CI\u002Fautomation\n- New library components: `enable_core.sh`, `wizard_utils.sh`, `task_sources.sh`\n\n**v0.10.1 - Bug Fixes & Monitor Path Corrections**\n- Fixed `ralph_monitor.sh` hardcoded paths for v0.10.0 compatibility\n- Fixed EXIT_SIGNAL parsing in JSON format\n- Added safety circuit breaker (force exit after 5 consecutive completion indicators)\n- Fixed checkbox parsing for indented markdown\n\n**v0.10.0 - .ralph\u002F Subfolder Structure (BREAKING CHANGE)**\n- **Breaking**: Moved all Ralph-specific files to `.ralph\u002F` subfolder\n- Project root stays clean: only `src\u002F`, `README.md`, and user files remain\n- Added `ralph-migrate` command for upgrading existing projects\n\n\u003Cdetails>\n\u003Csummary>Earlier versions (v0.9.x)\u003C\u002Fsummary>\n\n**v0.9.9 - EXIT_SIGNAL Gate & Uninstall Script**\n- Fixed premature exit bug: completion indicators now require Claude's explicit `EXIT_SIGNAL: true`\n- Added dedicated `uninstall.sh` script for clean Ralph removal\n\n**v0.9.8 - Modern CLI for PRD Import**\n- Modernized `ralph_import.sh` to use Claude Code CLI JSON output format\n- Enhanced error handling with structured JSON error messages\n\n**v0.9.7 - Session Lifecycle Management**\n- Complete session lifecycle management with automatic reset triggers\n- Added `--reset-session` CLI flag for manual session reset\n\n**v0.9.6 - JSON Output & Session Management**\n- Extended `parse_json_response()` to support Claude Code CLI JSON format\n- Added session management functions\n\n**v0.9.5 - v0.9.0** - PRD import tests, project setup tests, installation tests, prompt file fix, modern CLI commands, circuit breaker enhancements\n\n\u003C\u002Fdetails>\n\n### In Progress\n- Expanding test coverage\n- [Automated badge updates](#138)\n\n**Timeline to v1.0**: ~4 weeks | [Full roadmap](IMPLEMENTATION_PLAN.md) | **Contributions welcome!**\n\n## Features\n\n- **Autonomous Development Loop** - Continuously executes Claude Code with your project requirements\n- **Intelligent Exit Detection** - Dual-condition check requiring BOTH completion indicators AND explicit EXIT_SIGNAL\n- **Session Continuity** - Preserves context across loop iterations with automatic session management\n- **Session Expiration** - Configurable timeout (default: 24 hours) with automatic session reset\n- **Rate Limiting** - Built-in API call management with hourly limits and countdown timers\n- **5-Hour API Limit Handling** - Three-layer detection (timeout guard, JSON parsing, filtered text) with auto-wait for unattended mode\n- **Live Monitoring** - Real-time dashboard showing loop status, progress, and logs\n- **Task Management** - Structured approach with prioritized task lists and progress tracking\n- **Project Templates** - Quick setup for new projects with best-practice structure\n- **Interactive Project Setup** - `ralph-enable` wizard for existing projects with task import\n- **Configuration Files** - `.ralphrc` for project-specific settings and tool permissions\n- **Comprehensive Logging** - Detailed execution logs with timestamps and status tracking\n- **Configurable Timeouts** - Set execution timeout for Claude Code operations (1-120 minutes)\n- **Verbose Progress Mode** - Optional detailed progress updates during execution\n- **Response Analyzer** - AI-powered analysis of Claude Code responses with semantic understanding\n- **Circuit Breaker** - Advanced error detection with two-stage filtering, multi-line error matching, and automatic recovery\n- **CI\u002FCD Integration** - GitHub Actions workflow with automated testing\n- **Clean Uninstall** - Dedicated uninstall script for complete removal\n- **Live Streaming Output** - Real-time visibility into Claude Code execution with `--live` flag\n\n## Quick Start\n\nRalph has two phases: **one-time installation** and **per-project setup**.\n\n```\nINSTALL ONCE              USE MANY TIMES\n+-----------------+          +----------------------+\n| .\u002Finstall.sh    |    ->    | ralph-setup project1 |\n|                 |          | ralph-enable         |\n| Adds global     |          | ralph-import prd.md  |\n| commands        |          | ...                  |\n+-----------------+          +----------------------+\n```\n\n### Phase 1: Install Ralph (One Time Only)\n\nInstall Ralph globally on your system:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Ffrankbria\u002Fralph-claude-code.git\ncd ralph-claude-code\n.\u002Finstall.sh\n```\n\nThis adds `ralph`, `ralph-monitor`, `ralph-setup`, `ralph-import`, `ralph-migrate`, `ralph-enable`, and `ralph-enable-ci` commands to your PATH.\n\n> **Note**: You only need to do this once per system. After installation, you can delete the cloned repository if desired.\n\n### Phase 2: Initialize Projects (Per Project)\n\n#### Option A: Enable Ralph in Existing Project (Recommended)\n```bash\ncd my-existing-project\n\n# Interactive wizard - auto-detects project type and imports tasks\nralph-enable\n\n# Or with specific task source\nralph-enable --from beads\nralph-enable --from github --label \"sprint-1\"\nralph-enable --from prd .\u002Fdocs\u002Frequirements.md\n\n# Start autonomous development\nralph --monitor\n```\n\n#### Option B: Import Existing PRD\u002FSpecifications\n```bash\n# Convert existing PRD\u002Fspecs to Ralph format\nralph-import my-requirements.md my-project\ncd my-project\n\n# Review and adjust the generated files:\n# - .ralph\u002FPROMPT.md (Ralph instructions)\n# - .ralph\u002Ffix_plan.md (task priorities)\n# - .ralph\u002Fspecs\u002Frequirements.md (technical specs)\n\n# Start autonomous development\nralph --monitor\n```\n\n#### Option C: Create New Project from Scratch\n```bash\n# Create blank Ralph project\nralph-setup my-awesome-project\ncd my-awesome-project\n\n# Configure your project requirements manually\n# Edit .ralph\u002FPROMPT.md with your project goals\n# Edit .ralph\u002Fspecs\u002F with detailed specifications\n# Edit .ralph\u002Ffix_plan.md with initial priorities\n\n# Start autonomous development\nralph --monitor\n```\n\n### Ongoing Usage (After Setup)\n\nOnce Ralph is installed and your project is initialized:\n\n```bash\n# Navigate to any Ralph project and run:\nralph --monitor              # Integrated tmux monitoring (recommended)\n\n# Or use separate terminals:\nralph                        # Terminal 1: Ralph loop\nralph-monitor               # Terminal 2: Live monitor dashboard\n```\n\n### Uninstalling Ralph\n\nTo completely remove Ralph from your system:\n\n```bash\n# Run the uninstall script\n.\u002Funinstall.sh\n\n# Or if you deleted the repo, download and run:\ncurl -sL https:\u002F\u002Fraw.githubusercontent.com\u002Ffrankbria\u002Fralph-claude-code\u002Fmain\u002Funinstall.sh | bash\n```\n\n## Understanding Ralph Files\n\nAfter running `ralph-enable` or `ralph-import`, you'll have a `.ralph\u002F` directory with several files. Here's what each file does and whether you need to edit it:\n\n| File | Auto-Generated? | You Should... |\n|------|-----------------|---------------|\n| `.ralph\u002FPROMPT.md` | Yes (smart defaults) | **Review & customize** project goals and principles |\n| `.ralph\u002Ffix_plan.md` | Yes (can import tasks) | **Add\u002Fmodify** specific implementation tasks |\n| `.ralph\u002FAGENT.md` | Yes (detects build commands) | Rarely edit (auto-maintained by Ralph) |\n| `.ralph\u002Fspecs\u002F` | Empty directory | Add files when PROMPT.md isn't detailed enough |\n| `.ralph\u002Fspecs\u002Fstdlib\u002F` | Empty directory | Add reusable patterns and conventions |\n| `.ralphrc` | Yes (project-aware) | Rarely edit (sensible defaults) |\n\n### Key File Relationships\n\n```\nPROMPT.md (high-level goals)\n    ↓\nspecs\u002F (detailed requirements when needed)\n    ↓\nfix_plan.md (specific tasks Ralph executes)\n    ↓\nAGENT.md (build\u002Ftest commands - auto-maintained)\n```\n\n### When to Use specs\u002F\n\n- **Simple projects**: PROMPT.md + fix_plan.md is usually enough\n- **Complex features**: Add specs\u002Ffeature-name.md for detailed requirements\n- **Team conventions**: Add specs\u002Fstdlib\u002Fconvention-name.md for reusable patterns\n\nSee the [User Guide](docs\u002Fuser-guide\u002F) for detailed explanations and the [examples\u002F](examples\u002F) directory for realistic project configurations.\n\n## How It Works\n\nRalph operates on a simple but powerful cycle:\n\n1. **Read Instructions** - Loads `PROMPT.md` with your project requirements\n2. **Execute Claude Code** - Runs Claude Code with current context and priorities\n3. **Track Progress** - Updates task lists and logs execution results\n4. **Evaluate Completion** - Checks for exit conditions and project completion signals\n5. **Repeat** - Continues until project is complete or limits are reached\n\n### Intelligent Exit Detection\n\nRalph uses a **dual-condition check** to prevent premature exits during productive iterations:\n\n**Exit requires BOTH conditions:**\n1. `completion_indicators >= 2` (heuristic detection from natural language patterns)\n2. Claude's explicit `EXIT_SIGNAL: true` in the RALPH_STATUS block\n\n**Example behavior:**\n```\nLoop 5: Claude outputs \"Phase complete, moving to next feature\"\n        → completion_indicators: 3 (high confidence from patterns)\n        → EXIT_SIGNAL: false (Claude says more work needed)\n        → Result: CONTINUE (respects Claude's explicit intent)\n\nLoop 8: Claude outputs \"All tasks complete, project ready\"\n        → completion_indicators: 4\n        → EXIT_SIGNAL: true (Claude confirms done)\n        → Result: EXIT with \"project_complete\"\n```\n\n**Other exit conditions:**\n- All tasks in `.ralph\u002Ffix_plan.md` marked complete\n- Multiple consecutive \"done\" signals from Claude Code\n- Too many test-focused loops (indicating feature completeness)\n- Claude API 5-hour usage limit reached (with user prompt to wait or exit)\n\n## Enabling Ralph in Existing Projects\n\nThe `ralph-enable` command provides an interactive wizard for adding Ralph to existing projects:\n\n```bash\ncd my-existing-project\nralph-enable\n```\n\n**The wizard:**\n1. **Detects Environment** - Identifies project type (TypeScript, Python, etc.) and framework\n2. **Selects Task Sources** - Choose from beads, GitHub Issues, or PRD documents\n3. **Configures Settings** - Set tool permissions and loop parameters\n4. **Generates Files** - Creates `.ralph\u002F` directory and `.ralphrc` configuration\n5. **Verifies Setup** - Confirms all files are created correctly\n\n**Non-interactive mode for CI\u002Fautomation:**\n```bash\nralph-enable-ci                              # Sensible defaults\nralph-enable-ci --from github               # Import from GitHub Issues\nralph-enable-ci --project-type typescript   # Override detection\nralph-enable-ci --json                      # Machine-readable output\n```\n\n## Importing Existing Requirements\n\nRalph can convert existing PRDs, specifications, or requirement documents into the proper Ralph format using Claude Code.\n\n### Supported Formats\n- **Markdown** (.md) - Product requirements, technical specs\n- **Text files** (.txt) - Plain text requirements\n- **JSON** (.json) - Structured requirement data\n- **Word documents** (.docx) - Business requirements\n- **PDFs** (.pdf) - Design documents, specifications\n- **Any text-based format** - Ralph will intelligently parse the content\n\n### Usage Examples\n\n```bash\n# Convert a markdown PRD\nralph-import product-requirements.md my-app\n\n# Convert a text specification\nralph-import requirements.txt webapp\n\n# Convert a JSON API spec\nralph-import api-spec.json backend-service\n\n# Let Ralph auto-name the project from filename\nralph-import design-doc.pdf\n```\n\n### What Gets Generated\n\nRalph-import creates a complete project with:\n\n- **.ralph\u002FPROMPT.md** - Converted into Ralph development instructions\n- **.ralph\u002Ffix_plan.md** - Requirements broken down into prioritized tasks\n- **.ralph\u002Fspecs\u002Frequirements.md** - Technical specifications extracted from your document\n- **.ralphrc** - Project configuration file with tool permissions\n- **Standard Ralph structure** - All necessary directories and template files in `.ralph\u002F`\n\nThe conversion is intelligent and preserves your original requirements while making them actionable for autonomous development.\n\n## Configuration\n\n### Project Configuration (.ralphrc)\n\nEach Ralph project can have a `.ralphrc` configuration file:\n\n```bash\n# .ralphrc - Ralph project configuration\nPROJECT_NAME=\"my-project\"\nPROJECT_TYPE=\"typescript\"\n\n# Claude Code CLI command (auto-detected, override if needed)\nCLAUDE_CODE_CMD=\"claude\"\n# CLAUDE_CODE_CMD=\"npx @anthropic-ai\u002Fclaude-code\"  # Alternative: use npx\n\n# Shell init file — source before running claude (useful for zsh\u002Ffish users\n# whose PATH or env vars are only set in their shell's init file)\n#RALPH_SHELL_INIT_FILE=\"~\u002F.zshrc\"\n\n# Loop settings\nMAX_CALLS_PER_HOUR=100\nCLAUDE_TIMEOUT_MINUTES=15\nCLAUDE_OUTPUT_FORMAT=\"json\"\n# Token budget per hour (0 = disabled). One Claude call can use 100k+ tokens.\n#MAX_TOKENS_PER_HOUR=500000\n\n# Tool permissions\nALLOWED_TOOLS=\"Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest)\"\n\n# Session management\nSESSION_CONTINUITY=true\nSESSION_EXPIRY_HOURS=24\n\n# Circuit breaker thresholds\nCB_NO_PROGRESS_THRESHOLD=3\nCB_SAME_ERROR_THRESHOLD=5\n```\n\n### Rate Limiting & Circuit Breaker\n\nRalph includes intelligent rate limiting and circuit breaker functionality:\n\n```bash\n# Default: 100 calls per hour\nralph --calls 50\n\n# With integrated monitoring\nralph --monitor --calls 50\n\n# Check current usage (shows calls and tokens used this hour)\nralph --status\n```\n\nRate limiting supports two independent limits — both reset hourly:\n\n| Setting | Default | Description |\n|---------|---------|-------------|\n| `MAX_CALLS_PER_HOUR` | `100` | Max Claude invocations per hour |\n| `MAX_TOKENS_PER_HOUR` | `0` (disabled) | Max cumulative tokens per hour |\n\nToken tracking extracts `input_tokens + output_tokens` from each Claude response. A single call can consume 100k+ tokens, so `MAX_TOKENS_PER_HOUR` provides cost control that `MAX_CALLS_PER_HOUR` alone cannot.\n\nThe circuit breaker automatically:\n- Detects API errors and rate limit issues with advanced two-stage filtering\n- Opens circuit after 3 loops with no progress or 5 loops with same errors\n- Eliminates false positives from JSON fields containing \"error\"\n- Accurately detects stuck loops with multi-line error matching\n- Gradually recovers with half-open monitoring state\n- **Auto-recovers** after cooldown period (default: 30 minutes) — OPEN → HALF_OPEN → CLOSED\n- Provides detailed error tracking and logging with state history\n\n**Auto-recovery options:**\n```bash\n# Default: 30-minute cooldown before auto-recovery attempt\nCB_COOLDOWN_MINUTES=30     # Set in .ralphrc (0 = immediate)\n\n# Auto-reset on startup (for fully unattended operation)\nralph --auto-reset-circuit\n# Or set in .ralphrc: CB_AUTO_RESET=true\n```\n\n### Claude API 5-Hour Limit\n\nWhen Claude's 5-hour usage limit is reached, Ralph:\n1. Detects the limit using three-layer verification (timeout guard → structural JSON → filtered text fallback)\n2. Prompts you to choose:\n   - **Option 1**: Wait 60 minutes for the limit to reset (with countdown timer)\n   - **Option 2**: Exit gracefully\n3. **Unattended mode**: Auto-waits on prompt timeout (30s) instead of exiting\n4. Prevents false positives from echoed file content mentioning \"5-hour limit\"\n\n### Custom Prompts\n\n```bash\n# Use custom prompt file\nralph --prompt my_custom_instructions.md\n\n# With integrated monitoring\nralph --monitor --prompt my_custom_instructions.md\n```\n\n### Execution Timeouts\n\n```bash\n# Set Claude Code execution timeout (default: 15 minutes)\nralph --timeout 30  # 30-minute timeout for complex tasks\n\n# With monitoring and custom timeout\nralph --monitor --timeout 60  # 60-minute timeout\n\n# Short timeout for quick iterations\nralph --verbose --timeout 5  # 5-minute timeout with progress\n```\n\n### Verbose Mode\n\n```bash\n# Enable detailed progress updates during execution\nralph --verbose\n\n# Combine with other options\nralph --monitor --verbose --timeout 30\n```\n\n### Live Streaming Output\n\n```bash\n# Enable real-time visibility into Claude Code execution\nralph --live\n\n# Combine with monitoring for best experience\nralph --monitor --live\n\n# Live output is written to .ralph\u002Flive.log\ntail -f .ralph\u002Flive.log  # Watch in another terminal\n```\n\nLive streaming mode shows Claude Code's output in real-time as it works, providing visibility into what's happening during each loop iteration.\n\n### Session Continuity\n\nRalph maintains session context across loop iterations for improved coherence:\n\n```bash\n# Sessions are enabled by default with --continue flag\nralph --monitor                 # Uses session continuity\n\n# Start fresh without session context\nralph --no-continue             # Isolated iterations\n\n# Reset session manually (clears context)\nralph --reset-session           # Clears current session\n\n# Check session status\ncat .ralph\u002F.ralph_session              # View current session file\ncat .ralph\u002F.ralph_session_history      # View session transition history\n```\n\n**Session Auto-Reset Triggers:**\n- Circuit breaker opens (stagnation detected)\n- Manual interrupt (Ctrl+C \u002F SIGINT)\n- Project completion (graceful exit)\n- Manual circuit breaker reset (`--reset-circuit`)\n- Session expiration (default: 24 hours)\n\nSessions are persisted to `.ralph\u002F.ralph_session` with a configurable expiration (default: 24 hours). The last 50 session transitions are logged to `.ralph\u002F.ralph_session_history` for debugging.\n\n### Exit Thresholds\n\nModify these variables in `~\u002F.ralph\u002Fralph_loop.sh`:\n\n**Exit Detection Thresholds:**\n```bash\nMAX_CONSECUTIVE_TEST_LOOPS=3     # Exit after 3 test-only loops\nMAX_CONSECUTIVE_DONE_SIGNALS=2   # Exit after 2 \"done\" signals\nTEST_PERCENTAGE_THRESHOLD=30     # Flag if 30%+ loops are test-only\n```\n\n**Circuit Breaker Thresholds:**\n```bash\nCB_NO_PROGRESS_THRESHOLD=3       # Open circuit after 3 loops with no file changes\nCB_SAME_ERROR_THRESHOLD=5        # Open circuit after 5 loops with repeated errors\nCB_OUTPUT_DECLINE_THRESHOLD=70   # Open circuit if output declines by >70%\nCB_COOLDOWN_MINUTES=30           # Minutes before OPEN → HALF_OPEN auto-recovery\nCB_AUTO_RESET=false              # true = reset to CLOSED on startup (bypasses cooldown)\n```\n\n**Completion Indicators with EXIT_SIGNAL Gate:**\n\n| completion_indicators | EXIT_SIGNAL | Result |\n|-----------------------|-------------|--------|\n| >= 2 | `true` | **Exit** (\"project_complete\") |\n| >= 2 | `false` | **Continue** (Claude still working) |\n| >= 2 | missing | **Continue** (defaults to false) |\n| \u003C 2 | `true` | **Continue** (threshold not met) |\n\n## Project Structure\n\nRalph creates a standardized structure for each project with a `.ralph\u002F` subfolder for configuration:\n\n```\nmy-project\u002F\n├── .ralph\u002F                 # Ralph configuration and state (hidden folder)\n│   ├── PROMPT.md           # Main development instructions for Ralph\n│   ├── fix_plan.md        # Prioritized task list\n│   ├── AGENT.md           # Build and run instructions\n│   ├── specs\u002F              # Project specifications and requirements\n│   │   └── stdlib\u002F         # Standard library specifications\n│   ├── examples\u002F           # Usage examples and test cases\n│   ├── logs\u002F               # Ralph execution logs\n│   └── docs\u002Fgenerated\u002F     # Auto-generated documentation\n├── .ralphrc                # Ralph configuration file (tool permissions, settings)\n└── src\u002F                    # Source code implementation (at project root)\n```\n\n> **Migration**: If you have existing Ralph projects using the old flat structure, run `ralph-migrate` to automatically move files to the `.ralph\u002F` subfolder.\n\n## Best Practices\n\n### Writing Effective Prompts\n\n1. **Be Specific** - Clear requirements lead to better results\n2. **Prioritize** - Use `.ralph\u002Ffix_plan.md` to guide Ralph's focus\n3. **Set Boundaries** - Define what's in\u002Fout of scope\n4. **Include Examples** - Show expected inputs\u002Foutputs\n\n### Project Specifications\n\n- Place detailed requirements in `.ralph\u002Fspecs\u002F`\n- Use `.ralph\u002Ffix_plan.md` for prioritized task tracking\n- Keep `.ralph\u002FAGENT.md` updated with build instructions\n- Document key decisions and architecture\n\n### Monitoring Progress\n\n- Use `ralph-monitor` for live status updates\n- Check logs in `.ralph\u002Flogs\u002F` for detailed execution history\n- Monitor `.ralph\u002Fstatus.json` for programmatic access\n- Watch for exit condition signals\n\n## System Requirements\n\n- **Bash 4.0+** - For script execution\n- **Claude Code CLI** - `npm install -g @anthropic-ai\u002Fclaude-code` (or use npx — set `CLAUDE_CODE_CMD` in `.ralphrc`)\n- **tmux** - Terminal multiplexer for integrated monitoring (recommended)\n- **jq** - JSON processing for status tracking\n- **Git** - Version control (projects are initialized as git repos)\n- **GNU coreutils** - For the `timeout` command (execution timeouts)\n  - Linux: Pre-installed on most distributions\n  - macOS: Install via `brew install coreutils` (provides `gtimeout`)\n- **Standard Unix tools** - grep, date, etc.\n\n### Testing Requirements (Development)\n\nSee [TESTING.md](TESTING.md) for the comprehensive testing guide.\n\nIf you want to run the test suite:\n\n```bash\n# Install BATS testing framework\nnpm install -g bats bats-support bats-assert\n\n# Run all tests (566 tests)\nnpm test\n\n# Run specific test suites\nbats tests\u002Funit\u002Ftest_rate_limiting.bats\nbats tests\u002Funit\u002Ftest_exit_detection.bats\nbats tests\u002Funit\u002Ftest_json_parsing.bats\nbats tests\u002Funit\u002Ftest_cli_modern.bats\nbats tests\u002Funit\u002Ftest_cli_parsing.bats\nbats tests\u002Funit\u002Ftest_session_continuity.bats\nbats tests\u002Funit\u002Ftest_enable_core.bats\nbats tests\u002Funit\u002Ftest_task_sources.bats\nbats tests\u002Funit\u002Ftest_ralph_enable.bats\nbats tests\u002Funit\u002Ftest_wizard_utils.bats\nbats tests\u002Funit\u002Ftest_circuit_breaker_recovery.bats\nbats tests\u002Fintegration\u002Ftest_loop_execution.bats\nbats tests\u002Fintegration\u002Ftest_prd_import.bats\nbats tests\u002Fintegration\u002Ftest_project_setup.bats\nbats tests\u002Fintegration\u002Ftest_installation.bats\n\n# Run error detection and circuit breaker tests\n.\u002Ftests\u002Ftest_error_detection.sh\n.\u002Ftests\u002Ftest_stuck_loop_detection.sh\n```\n\nCurrent test status:\n- **566 tests** across 18 test files\n- **100% pass rate** (556\u002F556 passing)\n- Comprehensive unit and integration tests\n- Specialized tests for JSON parsing, CLI flags, circuit breaker, EXIT_SIGNAL behavior, enable wizard, and installation workflows\n\n> **Note on Coverage**: Bash code coverage measurement with kcov has fundamental limitations when tracing subprocess executions. Test pass rate (100%) is the quality gate. See [bats-core#15](https:\u002F\u002Fgithub.com\u002Fbats-core\u002Fbats-core\u002Fissues\u002F15) for details.\n\n### Installing tmux\n\n```bash\n# Ubuntu\u002FDebian\nsudo apt-get install tmux\n\n# macOS\nbrew install tmux\n\n# CentOS\u002FRHEL\nsudo yum install tmux\n```\n\n### Installing GNU coreutils (macOS)\n\nRalph uses the `timeout` command for execution timeouts. On macOS, you need to install GNU coreutils:\n\n```bash\n# Install coreutils (provides gtimeout)\nbrew install coreutils\n\n# Verify installation\ngtimeout --version\n```\n\nRalph automatically detects and uses `gtimeout` on macOS. No additional configuration is required after installation.\n\n## Monitoring and Debugging\n\n### Live Dashboard\n\n```bash\n# Integrated tmux monitoring (recommended)\nralph --monitor\n\n# Manual monitoring in separate terminal\nralph-monitor\n```\n\nShows real-time:\n- Current loop count and status\n- API calls used vs. limit\n- Recent log entries\n- Rate limit countdown\n\n**tmux Controls:**\n- `Ctrl+B` then `D` - Detach from session (keeps Ralph running)\n- `Ctrl+B` then `←\u002F→` - Switch between panes\n- `tmux list-sessions` - View active sessions\n- `tmux attach -t \u003Csession-name>` - Reattach to session\n\n### Status Checking\n\n```bash\n# JSON status output\nralph --status\n\n# Manual log inspection\ntail -f .ralph\u002Flogs\u002Fralph.log\n```\n\n### Common Issues\n\n- **Ralph exits silently on first loop** - Claude Code CLI may not be installed or not in PATH. Ralph validates the command at startup and shows installation instructions. If using npx, add `CLAUDE_CODE_CMD=\"npx @anthropic-ai\u002Fclaude-code\"` to `.ralphrc`\n- **Rate Limits** - Ralph automatically waits and displays countdown\n- **5-Hour API Limit** - Ralph detects and prompts for user action (wait or exit)\n- **Stuck Loops** - Check `fix_plan.md` for unclear or conflicting tasks\n- **Early Exit** - Review exit thresholds if Ralph stops too soon\n- **Premature Exit** - Check if Claude is setting `EXIT_SIGNAL: false` (Ralph now respects this)\n- **Execution Timeouts** - Increase `--timeout` value for complex operations\n- **Missing Dependencies** - Ensure Claude Code CLI and tmux are installed\n- **tmux Session Lost** - Use `tmux list-sessions` and `tmux attach` to reconnect\n- **Session Expired** - Sessions expire after 24 hours by default; use `--reset-session` to start fresh\n- **timeout: command not found (macOS)** - Install GNU coreutils: `brew install coreutils`\n- **Permission Denied** - Ralph halts when Claude Code is denied permission for commands:\n  1. Edit `.ralphrc` and update `ALLOWED_TOOLS` to include required tools\n  2. Common patterns: `Bash(npm *)`, `Bash(git *)`, `Bash(pytest)`\n  3. Run `ralph --reset-session` after updating `.ralphrc`\n  4. Restart with `ralph --monitor`\n\n## Contributing\n\nRalph is actively seeking contributors! We're working toward v1.0.0 with clear priorities and a detailed roadmap.\n\n**See [CONTRIBUTING.md](CONTRIBUTING.md) for the complete contributor guide** including:\n- Getting started and setup instructions\n- Development workflow and commit conventions\n- Code style guidelines\n- Testing requirements (100% pass rate mandatory)\n- Pull request process and code review guidelines\n- Quality standards and checklists\n\n### Quick Start\n\n```bash\n# Fork and clone\ngit clone https:\u002F\u002Fgithub.com\u002FYOUR_USERNAME\u002Fralph-claude-code.git\ncd ralph-claude-code\n\n# Install dependencies and run tests\nnpm install\nnpm test  # All 566 tests must pass\n```\n\n### Priority Contribution Areas\n\n1. **Test Implementation** - Help expand test coverage\n2. **Feature Development** - Log rotation, dry-run mode, metrics\n3. **Documentation** - Tutorials, troubleshooting guides, examples\n4. **Real-World Testing** - Use Ralph, report bugs, share feedback\n\n**Every contribution matters** - from fixing typos to implementing major features!\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Inspired by the [Ralph technique](https:\u002F\u002Fghuntley.com\u002Fralph\u002F) created by Geoffrey Huntley\n- Built for [Claude Code](https:\u002F\u002Fclaude.ai\u002Fcode) by Anthropic\n- Community feedback and contributions\n\n## Related Projects\n\n- [Claude Code](https:\u002F\u002Fclaude.ai\u002Fcode) - The AI coding assistant that powers Ralph\n- [Aider](https:\u002F\u002Fgithub.com\u002Fpaul-gauthier\u002Faider) - Original Ralph technique implementation\n\n---\n\n## Command Reference\n\n### Installation Commands (Run Once)\n```bash\n.\u002Finstall.sh              # Install Ralph globally\n.\u002Funinstall.sh            # Remove Ralph from system (dedicated script)\n.\u002Finstall.sh uninstall    # Alternative: Remove Ralph from system\n.\u002Finstall.sh --help       # Show installation help\nralph-migrate             # Migrate existing project to .ralph\u002F structure\n```\n\n### Ralph Loop Options\n```bash\nralph [OPTIONS]\n  -h, --help              Show help message\n  -c, --calls NUM         Set max calls per hour (default: 100)\n  -p, --prompt FILE       Set prompt file (default: PROMPT.md)\n  -s, --status            Show current status and exit\n  -m, --monitor           Start with tmux session and live monitor\n  -v, --verbose           Show detailed progress updates during execution\n  -l, --live              Enable live streaming output (real-time Claude Code visibility)\n  -t, --timeout MIN       Set Claude Code execution timeout in minutes (1-120, default: 15)\n  --output-format FORMAT  Set output format: json (default) or text\n  --allowed-tools TOOLS   Set allowed Claude tools (default: Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest))\n  --no-continue           Disable session continuity (start fresh each loop)\n  --reset-circuit         Reset the circuit breaker\n  --circuit-status        Show circuit breaker status\n  --auto-reset-circuit    Auto-reset circuit breaker on startup (bypasses cooldown)\n  --reset-session         Reset session state manually\n  -b, --backup            Enable automatic git backup branch before each loop (requires git)\n  --rollback [BRANCH]     Roll back to a backup branch (lists available branches if none given)\n```\n\n### Project Commands (Per Project)\n```bash\nralph-setup project-name     # Create new Ralph project\nralph-enable                 # Enable Ralph in existing project (interactive)\nralph-enable-ci              # Enable Ralph in existing project (non-interactive)\nralph-import prd.md project  # Convert PRD\u002Fspecs to Ralph project\nralph --monitor              # Start with integrated monitoring\nralph --status               # Check current loop status\nralph --verbose              # Enable detailed progress updates\nralph --timeout 30           # Set 30-minute execution timeout\nralph --calls 50             # Limit to 50 API calls per hour\nralph --reset-session        # Reset session state manually\nralph --live                 # Enable live streaming output\nralph-monitor                # Manual monitoring dashboard\n```\n\n### tmux Session Management\n```bash\ntmux list-sessions        # View active Ralph sessions\ntmux attach -t \u003Cname>     # Reattach to detached session\n# Ctrl+B then D           # Detach from session (keeps running)\n```\n\n---\n\n## Development Roadmap\n\nRalph is under active development with a clear path to v1.0.0. See [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md) for the complete roadmap.\n\n### Current Status: v0.11.5\n\n**What's Delivered:**\n- Core loop functionality with intelligent exit detection\n- **Dual-condition exit gate** (completion indicators + EXIT_SIGNAL)\n- Rate limiting (100 calls\u002Fhour) and circuit breaker pattern\n- Response analyzer with semantic understanding\n- **556 comprehensive tests** (100% pass rate)\n- **Live streaming output mode** for real-time Claude Code visibility\n- tmux integration and live monitoring\n- PRD import functionality with modern CLI JSON parsing\n- Installation system and project templates\n- Modern CLI commands with JSON output support\n- CI\u002FCD pipeline with GitHub Actions\n- **Interactive `ralph-enable` wizard for existing projects**\n- **`.ralphrc` configuration file support**\n- Session lifecycle management with auto-reset triggers\n- Session expiration with configurable timeout\n- Dedicated uninstall script\n\n**Test Coverage Breakdown:**\n- Unit Tests: 477 (CLI parsing, JSON, exit detection, rate limiting + token budgets, session continuity, enable wizard, live streaming, circuit breaker recovery, file protection, integrity checks)\n- Integration Tests: 136 (loop execution, edge cases, installation, project setup, PRD import)\n- Test Files: 18\n\n### Path to v1.0.0 (~4 weeks)\n\n**Enhanced Testing**\n- Installation and setup workflow tests\n- tmux integration tests\n- Monitor dashboard tests\n\n**Core Features**\n- Log rotation functionality\n- Dry-run mode\n\n**Advanced Features & Polish**\n- End-to-end tests\n- Final documentation and release prep\n\nSee [IMPLEMENTATION_STATUS.md](IMPLEMENTATION_STATUS.md) for detailed progress tracking.\n\n### How to Contribute\nRalph is seeking contributors! See [CONTRIBUTING.md](CONTRIBUTING.md) for the complete guide. Priority areas:\n1. **Test Implementation** - Help expand test coverage ([see plan](IMPLEMENTATION_PLAN.md))\n2. **Feature Development** - Log rotation, dry-run mode, metrics\n3. **Documentation** - Usage examples, tutorials, troubleshooting guides\n4. **Bug Reports** - Real-world usage feedback and edge cases\n\n---\n\n**Ready to let AI build your project?** Start with `.\u002Finstall.sh` and let Ralph take it from there!\n\n## Star History\n\n[![Star History Chart](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ffrankbria_ralph-claude-code_readme_f03ddc31ea18.png)](https:\u002F\u002Fwww.star-history.com\u002F#frankbria\u002Fralph-claude-code&type=date&legend=top-left)\n","# Ralph 用于 Claude Code\n\n[![CI](https:\u002F\u002Fgithub.com\u002Ffrankbria\u002Fralph-claude-code\u002Factions\u002Fworkflows\u002Ftest.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Ffrankbria\u002Fralph-claude-code\u002Factions\u002Fworkflows\u002Ftest.yml)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-blue.svg)](LICENSE)\n![版本](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fversion-0.11.5-blue)\n![测试](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Ftests-556%20passing-green)\n[![GitHub Issues](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fissues\u002Ffrankbria\u002Fralph-claude-code)](https:\u002F\u002Fgithub.com\u002Ffrankbria\u002Fralph-claude-code\u002Fissues)\n[![被 Awesome Claude Code 提及](https:\u002F\u002Fawesome.re\u002Fmentioned-badge.svg)](https:\u002F\u002Fgithub.com\u002Fhesreallyhim\u002Fawesome-claude-code)\n[![在 X 上关注](https:\u002F\u002Fimg.shields.io\u002Ftwitter\u002Ffollow\u002FFrankBria18044?style=social)](https:\u002F\u002Fx.com\u002FFrankBria18044)\n\n> **具备智能退出检测与速率限制的自主 AI 开发循环**\n\nRalph 是 Geoffrey Huntley 针对 Claude Code 所提出技术的一种实现，该技术能够支持持续的自主开发周期，并以 [Ralph Wiggum](https:\u002F\u002Fghuntley.com\u002Fralph\u002F) 的名字命名。它允许 Claude Code 在内置的安全机制（如防止无限循环和 API 过度使用）保障下，不断迭代改进您的项目直至完成。\n\n**一次安装，随处可用** - Ralph 可作为全局命令，在任何目录中均可使用。\n\n## 项目状态\n\n**版本**: v0.11.5 - 正在积极开发\n**核心功能**: 已实现并经过测试\n**测试覆盖率**: 566 个测试，通过率 100%\n\n### 目前已实现的功能\n- 具备智能退出检测的自主开发循环\n- **双重条件退出机制**：必须同时满足完成标志和显式 EXIT_SIGNAL 才能退出\n- 每小时重置的速率限制（100 次\u002F小时，可配置）\n- 带有高级错误检测的熔断器（防止失控循环）\n- 具有语义理解能力的响应分析器，支持两阶段错误过滤\n- **支持 JSON 输出格式，并自动回退至文本解析**\n- **通过 `--resume` 标志实现会话连续性，保留上下文（无会话劫持）**\n- **会话过期机制，可配置超时时间（默认 24 小时）**\n- **现代化 CLI 标志：`--output-format`、`--allowed-tools`、`--no-continue`**\n- **交互式项目启用向导 `ralph-enable`**\n- **`.ralphrc` 配置文件，用于项目设置**\n- **通过 `--live` 标志提供实时流输出，便于查看 Claude Code 的执行过程**\n- 多行错误匹配，精准检测卡死循环\n- 针对 5 小时 API 使用上限的处理，并配合用户提示\n- 与 tmux 集成，方便实时监控\n- 支持 PRD 导入功能\n- **基于 GitHub Actions 的 CI\u002FCD 流水线**\n- **专用卸载脚本，确保干净彻底地移除**\n\n### 最新改进\n\n**v0.11.5 - 社区修复的 bug**（最新版本）\n- 修复了 API 限制误报：超时（退出码 124）不再被误认为是 API 的 5 小时限制 (#183)\n- 三层 API 限制检测机制：超时保护 → 结构化 JSON（`rate_limit_event`）→ 过滤文本回退\n- 无人值守模式：API 限制提示现在会在超时时自动等待，而不是直接退出\n- 修复了 Bash 3.x 兼容性问题：将 `${,,}` 小写替换语法替换为 POSIX 的 `tr` 命令 (#187)\n- 新增 8 个 API 限制检测测试用例（测试总数从 548 增加到 566）\n\n**v0.11.4 - Bug 修复与兼容性改进**\n- 修复了进度检测问题：循环中的 Git 提交现在会被计入进度 (#141)\n- 修复了复选框正则表达式：日期条目 `[2026-01-29]` 不再被误认为是复选框 (#144)\n- 修复了会话劫持问题：使用 `--resume \u003Csession_id>` 替代 `--continue` (#151)\n- 修复了 `EXIT_SIGNAL` 覆盖问题：当 `STATUS: COMPLETE` 且 `EXIT_SIGNAL: false` 时，现在会继续运行 (#146)\n- 修复了 ralph-import 无限挂起的问题（添加了用于非交互模式的 `--print` 标志）\n- 修复了 ralph-import 绝对路径处理问题\n- 修复了 macOS 上使用 Homebrew coreutils 时的跨平台日期命令问题\n- 添加了可通过环境变量配置的熔断阈值 (#99)\n- 为非零 `base-index` 配置增加了 tmux 支持\n- 新增 13 个回归测试用例，用于测试进度检测和复选框正则表达式\n\n**v0.11.3 - 直播流与 beads 修复**\n- 添加了实时 Claude Code 可见性的直播输出模式，通过 `--live` 标志实现 (#125)\n- 修复了使用正确 `bd list` 参数导入 beads 任务的问题 (#150)\n- 应用了 CodeRabbit 审查修复：驼峰命名变量、尊重状态的回退逻辑、jq 防御措施\n- 新增 12 个测试用例，用于改进直播流和 beads 导入功能\n\n**v0.11.2 - 设置权限修复**\n- 修复了问题 #136：`ralph-setup` 现在会创建具有一致工具权限的 `.ralphrc` 文件\n- 更新了默认的 `ALLOWED_TOOLS` 列表，加入了 `Edit`、`Bash(npm *)` 和 `Bash(pytest)`\n- `ralph-setup` 和 `ralph-enable` 现在都会生成完全相同的 `.ralphrc` 配置文件\n- Monitor 现在会将所有 CLI 参数转发给内部的 ralph 循环 (#126)\n- 新增 16 个测试用例，用于测试权限和参数转发功能\n\n**v0.11.1 - 完成指标修复**\n- 修复了 JSON 输出模式下恰好执行 5 次循环后过早退出的问题\n- `completion_indicators` 现在仅在 `EXIT_SIGNAL: true` 时才会累计\n- 与文档中记录的双条件退出机制保持一致\n\n**v0.11.0 - Ralph 启用向导**\n- 添加了 `ralph-enable` 交互式向导，用于在现有项目中启用 Ralph\n- 五阶段向导：环境检测 → 任务来源选择 → 配置 → 文件生成 → 验证\n- 自动检测项目类型（TypeScript、Python、Rust、Go）和框架（Next.js、FastAPI、Django）\n- 可从 beads、GitHub Issues 或 PRD 文档中导入任务\n- 添加了用于 CI\u002F自动化流程的非交互式版本 `ralph-enable-ci`\n- 新增库组件：`enable_core.sh`、`wizard_utils.sh`、`task_sources.sh`\n\n**v0.10.1 - Bug 修复与 Monitor 路径修正**\n- 修复了 `ralph_monitor.sh` 中硬编码的路径，以确保与 v0.10.0 兼容\n- 修复了 JSON 格式中 `EXIT_SIGNAL` 的解析问题\n- 添加了安全熔断机制（连续出现 5 个完成指标后强制退出）\n- 修复了缩进 Markdown 中的复选框解析问题\n\n**v0.10.0 - .ralph\u002F 子文件夹结构（破坏性变更）**\n- **破坏性变更**：所有 Ralph 特定文件均移至 `.ralph\u002F` 子文件夹\n- 项目根目录保持整洁：仅保留 `src\u002F`、`README.md` 和用户文件\n- 添加了 `ralph-migrate` 命令，用于升级现有项目\n\n\u003Cdetails>\n\u003Csummary>早期版本（v0.9.x）\u003C\u002Fsummary>\n\n**v0.9.9 - EXIT_SIGNAL 门控与卸载脚本**\n- 修复了过早退出的 bug：完成指标现在需要 Claude 明确的 `EXIT_SIGNAL: true`\n- 添加了专门的 `uninstall.sh` 脚本，用于干净地移除 Ralph\n\n**v0.9.8 - 用于 PRD 导入的现代化 CLI**\n- 对 `ralph_import.sh` 进行了现代化改造，采用 Claude Code CLI 的 JSON 输出格式\n- 增强了错误处理能力，使用结构化的 JSON 错误信息\n\n**v0.9.7 - 会话生命周期管理**\n- 实现了完整的会话生命周期管理，并设置了自动重置触发条件\n- 添加了 `--reset-session` CLI 标志，用于手动重置会话\n\n**v0.9.6 - JSON 输出与会话管理**\n- 扩展了 `parse_json_response()` 函数，以支持 Claude Code CLI 的 JSON 格式\n- 添加了会话管理相关函数\n\n**v0.9.5 - v0.9.0** - 包括 PRD 导入测试、项目设置测试、安装测试、提示文件修复、现代化 CLI 命令以及熔断器增强等功能\n\n\u003C\u002Fdetails>\n\n### 进展中\n- 扩展测试覆盖率\n- [自动化徽章更新](#138)\n\n**迈向 v1.0 的时间表**：约 4 周 | [完整路线图](IMPLEMENTATION_PLAN.md) | **欢迎贡献！**\n\n## 功能特性\n\n- **自主开发循环** - 根据您的项目需求持续执行 Claude Code\n- **智能退出检测** - 双条件检查，需同时满足完成指标和明确的 `EXIT_SIGNAL`\n- **会话连续性** - 通过自动会话管理，在循环迭代之间保持上下文\n- **会话过期** - 可配置的超时时间（默认 24 小时），并自动重置会话\n- **速率限制** - 内置 API 调用管理，包括每小时限制和倒计时定时器\n- **5 小时 API 限制处理** - 三层检测机制（超时保护、JSON 解析、过滤文本），并针对无人值守模式自动等待\n- **实时监控** - 实时仪表盘显示循环状态、进度和日志\n- **任务管理** - 结构化方法，提供优先级任务列表和进度跟踪\n- **项目模板** - 快速搭建新项目，采用最佳实践结构\n- **交互式项目设置** - `ralph-enable` 向导，适用于现有项目及任务导入\n- **配置文件** - `.ralphrc` 用于项目特定设置和工具权限\n- **全面日志记录** - 详细的执行日志，包含时间戳和状态跟踪\n- **可配置超时** - 可为 Claude Code 操作设置执行超时（1–120 分钟）\n- **详细进度模式** - 执行过程中可选择详细的进度更新\n- **响应分析器** - 基于 AI 的 Claude Code 响应分析，具备语义理解能力\n- **熔断器** - 先进的错误检测机制，包括两阶段过滤、多行错误匹配和自动恢复\n- **CI\u002FCD 集成** - GitHub Actions 工作流，支持自动化测试\n- **干净卸载** - 专用卸载脚本，实现彻底移除\n- **直播输出** - 通过 `--live` 标志实现实时查看 Claude Code 执行情况\n\n## 快速入门\n\nRalph 包括两个阶段：**一次性安装**和**每个项目的设置**。\n\n```\n一次性安装              多次使用\n+-----------------+          +----------------------+\n| .\u002Finstall.sh    |    ->    | ralph-setup project1 |\n|                 |          | ralph-enable         |\n| 添加全局命令    |          | ralph-import prd.md  |\n|                 |          | ...                  |\n+-----------------+          +----------------------+\n```\n\n### 第一阶段：安装 Ralph（仅需执行一次）\n\n在您的系统上全局安装 Ralph：\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Ffrankbria\u002Fralph-claude-code.git\ncd ralph-claude-code\n.\u002Finstall.sh\n```\n\n这会将 `ralph`、`ralph-monitor`、`ralph-setup`、`ralph-import`、`ralph-migrate`、`ralph-enable` 和 `ralph-enable-ci` 命令添加到您的 PATH 中。\n\n> **注意**：您只需在每个系统上执行一次此操作。安装完成后，您可以根据需要删除克隆的仓库。\n\n### 第二阶段：初始化项目（按项目进行）\n\n#### 选项 A：在现有项目中启用 Ralph（推荐）\n```bash\ncd my-existing-project\n\n# 交互式向导 - 自动检测项目类型并导入任务\nralph-enable\n\n# 或者指定任务来源\nralph-enable --from beads\nralph-enable --from github --label \"sprint-1\"\nralph-enable --from prd .\u002Fdocs\u002Frequirements.md\n\n# 开始自主开发\nralph --monitor\n```\n\n#### 选项 B：导入现有的 PRD\u002F规格文档\n```bash\n# 将现有的 PRD\u002F规格文档转换为 Ralph 格式\nralph-import my-requirements.md my-project\ncd my-project\n\n# 审查并调整生成的文件：\n# - .ralph\u002FPROMPT.md（Ralph 指令）\n# - .ralph\u002Ffix_plan.md（任务优先级）\n# - .ralph\u002Fspecs\u002Frequirements.md（技术规格）\n\n# 开始自主开发\nralph --monitor\n```\n\n#### 选项 C：从头创建新项目\n```bash\n# 创建空白的 Ralph 项目\nralph-setup my-awesome-project\ncd my-awesome-project\n\n# 手动配置项目需求\n# 编辑 .ralph\u002FPROMPT.md 以设定项目目标\n# 编辑 .ralph\u002Fspecs\u002F 以提供详细规格\n# 编辑 .ralph\u002Ffix_plan.md 以设定初始优先级\n\n# 开始自主开发\nralph --monitor\n```\n\n### 后续使用（设置完成后）\n\n一旦 Ralph 安装完成且项目已初始化：\n\n```bash\n# 导航到任意 Ralph 项目并运行：\nralph --monitor              # 集成 tmux 监控（推荐）\n\n# 或者使用独立终端：\nralph                        # 终端 1：Ralph 循环\nralph-monitor               # 终端 2：实时监控仪表盘\n```\n\n### 卸载 Ralph\n\n要从您的系统中完全移除 Ralph：\n\n```bash\n# 运行卸载脚本\n.\u002Funinstall.sh\n\n# 或者如果您已删除仓库，可下载并运行：\ncurl -sL https:\u002F\u002Fraw.githubusercontent.com\u002Ffrankbria\u002Fralph-claude-code\u002Fmain\u002Funinstall.sh | bash\n```\n\n## 理解 Ralph 文件\n\n运行 `ralph-enable` 或 `ralph-import` 后，您将获得一个 `.ralph\u002F` 目录，其中包含多个文件。以下是每个文件的作用以及是否需要编辑它们：\n\n| 文件 | 自动生成？ | 您应该... |\n|------|-----------------|---------------|\n| `.ralph\u002FPROMPT.md` | 是（智能默认值） | **审查并自定义** 项目目标和原则 |\n| `.ralph\u002Ffix_plan.md` | 是（可导入任务） | **添加\u002F修改** 具体实现任务 |\n| `.ralph\u002FAGENT.md` | 是（检测构建命令） | 很少编辑（由 Ralph 自动维护） |\n| `.ralph\u002Fspecs\u002F` | 空目录 | 当 PROMPT.md 不够详细时添加文件 |\n| `.ralph\u002Fspecs\u002Fstdlib\u002F` | 空目录 | 添加可重用的模式和规范 |\n| `.ralphrc` | 是（项目感知） | 很少编辑（合理默认值） |\n\n### 主要文件之间的关系\n\n```\nPROMPT.md（高层次目标）\n    ↓\nspecs\u002F（必要时的详细需求）\n    ↓\nfix_plan.md（Ralph 执行的具体任务）\n    ↓\nAGENT.md（构建\u002F测试命令 - 自动维护）\n```\n\n### 何时使用 specs\u002F\n\n- **简单项目**：通常 PROMPT.md + fix_plan.md 就足够了\n- **复杂功能**：添加 specs\u002Ffeature-name.md 以提供详细需求\n- **团队规范**：添加 specs\u002Fstdlib\u002Fconvention-name.md 以提供可重用模式\n\n有关详细说明，请参阅 [用户指南](docs\u002Fuser-guide\u002F)；有关实际项目配置，请参阅 [examples\u002F](examples\u002F) 目录。\n\n## 工作原理\n\nRalph 基于一个简单而强大的循环运作：\n\n1. **读取指令** - 加载包含项目需求的 `PROMPT.md`\n2. **执行 Claude 代码** - 在当前上下文和优先级下运行 Claude 代码\n3. **跟踪进度** - 更新任务列表并记录执行结果\n4. **评估完成情况** - 检查退出条件及项目完成信号\n5. **重复** - 直到项目完成或达到限制为止\n\n### 智能退出检测\n\nRalph 使用 **双重条件检查** 来防止在高效迭代过程中过早退出：\n\n**退出需要同时满足以下两个条件：**\n1. `completion_indicators >= 2`（基于自然语言模式的启发式检测）\n2. Claude 在 RALPH_STATUS 块中明确发出 `EXIT_SIGNAL: true`\n\n**示例行为：**\n```\n第 5 轮：Claude 输出“阶段完成，进入下一功能”\n        → completion_indicators: 3（基于模式的高度信心）\n        → EXIT_SIGNAL: false（Claude 表示还需要更多工作）\n        → 结果：继续（尊重 Claude 的明确意图）\n\n第 8 轮：Claude 输出“所有任务完成，项目准备就绪”\n        → completion_indicators: 4\n        → EXIT_SIGNAL: true（Claude 确认已完成）\n        → 结果：退出，并显示“project_complete”\n```\n\n**其他退出条件：**\n- `.ralph\u002Ffix_plan.md` 中的所有任务均标记为完成\n- Claude 代码连续多次发出“完成”信号\n- 测试导向的循环次数过多（表明功能已完成）\n- Claude API 使用时间达到 5 小时上限（此时会提示用户等待或退出）\n\n## 在现有项目中启用 Ralph\n\n`ralph-enable` 命令提供了一个交互式向导，用于将 Ralph 添加到现有项目中：\n\n```bash\ncd my-existing-project\nralph-enable\n```\n\n**向导流程：**\n1. **检测环境** - 识别项目类型（TypeScript、Python 等）和框架\n2. **选择任务来源** - 可从 beads、GitHub Issues 或 PRD 文档中选择\n3. **配置设置** - 设置工具权限和循环参数\n4. **生成文件** - 创建 `.ralph\u002F` 目录和 `.ralphrc` 配置文件\n5. **验证设置** - 确认所有文件均已正确创建\n\n**非交互模式，适用于 CI\u002F自动化：**\n```bash\nralph-enable-ci                              # 合理默认值\nralph-enable-ci --from github               # 从 GitHub Issues 导入\nralph-enable-ci --project-type typescript   # 覆盖自动检测\nralph-enable-ci --json                      # 机器可读输出\n```\n\n## 导入现有需求\n\nRalph 可以使用 Claude 代码将现有的 PRD、规格文档或需求文件转换为适当的 Ralph 格式。\n\n### 支持的格式\n- **Markdown** (.md) - 产品需求、技术规格\n- **文本文件** (.txt) - 纯文本需求\n- **JSON** (.json) - 结构化需求数据\n- **Word 文档** (.docx) - 商业需求\n- **PDF** (.pdf) - 设计文档、规格\n- **任何基于文本的格式** - Ralph 会智能解析内容\n\n### 使用示例\n\n```bash\n# 转换 Markdown 格式的 PRD\nralph-import product-requirements.md my-app\n\n# 转换文本规格\nralph-import requirements.txt webapp\n\n# 转换 JSON 格式的 API 规格\nralph-import api-spec.json backend-service\n\n# 让 Ralph 根据文件名自动命名项目\nralph-import design-doc.pdf\n```\n\n### 生成的内容\n\nRalph-import 会创建一个完整的项目，包含以下内容：\n\n- **.ralph\u002FPROMPT.md** - 转换为 Ralph 开发指令\n- **.ralph\u002Ffix_plan.md** - 将需求分解为优先级任务\n- **.ralph\u002Fspecs\u002Frequirements.md** - 从您的文档中提取的技术规格\n- **.ralphrc** - 包含工具权限的项目配置文件\n- **标准 Ralph 结构** - `.ralph\u002F` 中的所有必要目录和模板文件\n\n转换过程智能且保留了您原有的需求，同时使其可被自主开发所执行。\n\n## 配置\n\n### 项目配置 (.ralphrc)\n\n每个 Ralph 项目都可以有一个 `.ralphrc` 配置文件：\n\n```bash\n# .ralphrc - Ralph 项目配置\nPROJECT_NAME=\"my-project\"\nPROJECT_TYPE=\"typescript\"\n\n# Claude Code CLI 命令（自动检测，如有需要可覆盖）\nCLAUDE_CODE_CMD=\"claude\"\n# CLAUDE_CODE_CMD=\"npx @anthropic-ai\u002Fclaude-code\"  # 替代方案：使用 npx\n\n# Shell 初始化文件 — 在运行 claude 之前先加载（适用于 zsh\u002Ffish 用户，\n# 其 PATH 或环境变量仅在其 shell 的初始化文件中设置）\n#RALPH_SHELL_INIT_FILE=\"~\u002F.zshrc\"\n\n# 循环设置\nMAX_CALLS_PER_HOUR=100\nCLAUDE_TIMEOUT_MINUTES=15\nCLAUDE_OUTPUT_FORMAT=\"json\"\n# 每小时令牌预算（0 = 禁用）。一次 Claude 调用可能消耗 10 万+ 令牌。\n#MAX_TOKENS_PER_HOUR=500000\n\n# 工具权限\nALLOWED_TOOLS=\"Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest)\"\n\n# 会话管理\nSESSION_CONTINUITY=true\nSESSION_EXPIRY_HOURS=24\n\n# 断路器阈值\nCB_NO_PROGRESS_THRESHOLD=3\nCB_SAME_ERROR_THRESHOLD=5\n```\n\n### 速率限制与断路器\n\nRalph 包含智能的速率限制和断路器功能：\n\n```bash\n# 默认：每小时 100 次调用\nralph --calls 50\n\n# 带集成监控\nralph --monitor --calls 50\n\n# 查看当前使用情况（显示本小时已使用的调用次数和令牌数）\nralph --status\n```\n\n速率限制支持两个独立的限制——两者每小时重置一次：\n\n| 设置 | 默认 | 描述 |\n|---------|---------|-------------|\n| `MAX_CALLS_PER_HOUR` | `100` | 每小时最大 Claude 调用次数 |\n| `MAX_TOKENS_PER_HOUR` | `0`（禁用） | 每小时累计最大令牌数 |\n\n令牌跟踪会从每次 Claude 响应中提取 `input_tokens + output_tokens`。单次调用可能消耗 10 万+ 令牌，因此 `MAX_TOKENS_PER_HOUR` 提供了 `MAX_CALLS_PER_HOUR` 单独无法实现的成本控制。\n\n断路器会自动：\n- 使用高级两阶段过滤检测 API 错误和速率限制问题\n- 在连续 3 次循环无进展或连续 5 次循环出现相同错误时打开断路器\n- 消除因 JSON 字段中包含“error”而导致的误报\n- 通过多行错误匹配准确检测卡住的循环\n- 逐步恢复，进入半开监控状态\n- **自动恢复**在冷却期后（默认：30 分钟）——OPEN → HALF_OPEN → CLOSED\n- 提供详细的错误跟踪和日志记录，包括状态历史\n\n**自动恢复选项：**\n```bash\n# 默认：自动恢复尝试前有 30 分钟的冷却期\nCB_COOLDOWN_MINUTES=30     # 在 .ralphrc 中设置（0 = 立即）\n\n# 启动时自动重置断路器（用于完全无人值守的操作）\nralph --auto-reset-circuit\n# 或在 .ralphrc 中设置：CB_AUTO_RESET=true\n```\n\n### Claude API 5 小时限制\n\n当 Claude 的 5 小时使用限制达到时，Ralph 会：\n1. 使用三层验证检测该限制（超时保护 → 结构化 JSON → 过滤后的文本回退）\n2. 提示您选择：\n   - **选项 1**：等待 60 分钟以重置限制（带倒计时）\n   - **选项 2**：优雅退出\n3. **无人值守模式**：在提示超时（30 秒）后自动等待，而不是退出\n4. 防止因回显的文件内容提及“5 小时限制”而产生的误报。\n\n### 自定义提示\n\n```bash\n# 使用自定义提示文件\nralph --prompt my_custom_instructions.md\n\n# 带集成监控\nralph --monitor --prompt my_custom_instructions.md\n```\n\n### 执行超时\n\n```bash\n# 设置 Claude Code 执行超时（默认：15 分钟）\nralph --timeout 30  # 复杂任务的 30 分钟超时\n\n# 带监控和自定义超时\nralph --monitor --timeout 60  # 60 分钟超时\n\n# 快速迭代的短超时\nralph --verbose --timeout 5  # 带进度的 5 分钟超时\n```\n\n### 详细模式\n\n```bash\n# 在执行过程中启用详细的进度更新\nralph --verbose\n\n# 可与其他选项结合使用\nralph --monitor --verbose --timeout 30\n```\n\n### 实时输出流\n\n```bash\n# 启用对 Claude Code 执行的实时可见性\nralph --live\n\n# 与监控结合使用以获得最佳体验\nralph --monitor --live\n\n# 实时输出会写入 .ralph\u002Flive.log\ntail -f .ralph\u002Flive.log  # 在另一个终端查看\n```\n\n实时流模式会实时显示 Claude Code 的输出，让您清楚地了解每次循环迭代中正在发生的事情。\n\n### 会话连续性\n\nRalph 会在循环迭代之间保持会话上下文，以提高连贯性：\n\n```bash\n# 默认启用会话连续性，只需使用 --continue 标志\nralph --monitor                 # 使用会话连续性\n\n# 不带会话上下文从头开始\nralph --no-continue             # 独立的迭代\n\n# 手动重置会话（清除上下文）\nralph --reset-session           # 清除当前会话\n\n# 查看会话状态\ncat .ralph\u002F.ralph_session              # 查看当前会话文件\ncat .ralph\u002F.ralph_session_history      # 查看会话过渡历史\n```\n\n**会话自动重置触发条件：**\n- 断路器打开（检测到停滞）\n- 手动中断（Ctrl+C \u002F SIGINT）\n- 项目完成（优雅退出）\n- 手动重置断路器（`--reset-circuit`）\n- 会话到期（默认：24 小时）\n\n会话会持久化到 `.ralph\u002F.ralph_session`，其有效期可配置（默认：24 小时）。最近 50 次会话过渡会被记录到 `.ralph\u002F.ralph_session_history` 中，以便调试。\n\n### 退出阈值\n\n在 `~\u002F.ralph\u002Fralph_loop.sh` 中修改这些变量：\n\n**退出检测阈值：**\n```bash\nMAX_CONSECUTIVE_TEST_LOOPS=3     # 经过3次仅测试循环后退出\nMAX_CONSECUTIVE_DONE_SIGNALS=2   # 收到2次“完成”信号后退出\nTEST_PERCENTAGE_THRESHOLD=30     # 如果30%以上的循环仅为测试循环，则发出警告\n```\n\n**熔断器阈值：**\n```bash\nCB_NO_PROGRESS_THRESHOLD=3       # 连续3次循环无文件更改时触发熔断\nCB_SAME_ERROR_THRESHOLD=5        # 连续5次循环出现重复错误时触发熔断\nCB_OUTPUT_DECLINE_THRESHOLD=70   # 输出下降超过70%时触发熔断\nCB_COOLDOWN_MINUTES=30           # 从“OPEN”状态自动恢复为“HALF_OPEN”状态前的冷却时间（分钟）\nCB_AUTO_RESET=false              # true = 启动时重置为“CLOSED”状态（绕过冷却期）\n```\n\n**完成指标与 EXIT_SIGNAL 门控：**\n\n| completion_indicators | EXIT_SIGNAL | 结果 |\n|-----------------------|-------------|--------|\n| >= 2 | `true` | **退出**（“project_complete”） |\n| >= 2 | `false` | **继续**（Claude仍在工作） |\n| >= 2 | 缺失 | **继续**（默认为 false） |\n| \u003C 2 | `true` | **继续**（未达到阈值） |\n\n## 项目结构\n\nRalph 为每个项目创建标准化的结构，其中包含用于配置的 `.ralph\u002F` 子文件夹：\n\n```\nmy-project\u002F\n├── .ralph\u002F                 # Ralph 配置与状态文件（隐藏文件夹）\n│   ├── PROMPT.md           # Ralph 的主要开发说明\n│   ├── fix_plan.md         # 优先级任务列表\n│   ├── AGENT.md            # 构建和运行说明\n│   ├── specs\u002F              # 项目规格与需求\n│   │   └── stdlib\u002F         # 标准库规格\n│   ├── examples\u002F           # 使用示例与测试用例\n│   ├── logs\u002F               # Ralph 执行日志\n│   └── docs\u002Fgenerated\u002F     # 自动生成的文档\n├── .ralphrc                # Ralph 配置文件（工具权限、设置）\n└── src\u002F                    # 源代码实现（位于项目根目录）\n```\n\n> **迁移**：如果您有使用旧式扁平结构的现有 Ralph 项目，请运行 `ralph-migrate` 自动将文件移至 `.ralph\u002F` 子文件夹。\n\n## 最佳实践\n\n### 编写有效提示\n\n1. **明确具体** - 清晰的需求带来更好的结果\n2. **优先排序** - 使用 `.ralph\u002Ffix_plan.md` 引导 Ralph 的关注点\n3. **设定边界** - 定义范围内外的内容\n4. **包含示例** - 展示预期的输入\u002F输出\n\n### 项目规格\n\n- 将详细需求放在 `.ralph\u002Fspecs\u002F` 中\n- 使用 `.ralph\u002Ffix_plan.md` 进行优先级任务跟踪\n- 保持 `.ralph\u002FAGENT.md` 更新以包含构建指令\n- 记录关键决策和架构设计\n\n### 监控进度\n\n- 使用 `ralph-monitor` 获取实时状态更新\n- 查看 `.ralph\u002Flogs\u002F` 中的日志以了解详细的执行历史\n- 监控 `.ralph\u002Fstatus.json` 以进行程序化访问\n- 注意退出条件信号\n\n## 系统要求\n\n- **Bash 4.0+** - 用于脚本执行\n- **Claude Code CLI** - `npm install -g @anthropic-ai\u002Fclaude-code`（或使用 npx — 在 `.ralphrc` 中设置 `CLAUDE_CODE_CMD`）\n- **tmux** - 终端多路复用器，推荐用于集成监控\n- **jq** - 用于状态跟踪的 JSON 处理工具\n- **Git** - 版本控制（项目初始化为 Git 仓库）\n- **GNU coreutils** - 提供 `timeout` 命令（执行超时）\n  - Linux：大多数发行版已预装\n  - macOS：通过 `brew install coreutils` 安装（提供 `gtimeout`）\n- **标准 Unix 工具** - grep、date 等\n\n### 测试要求（开发）\n\n请参阅 [TESTING.md](TESTING.md) 以获取完整的测试指南。\n\n如果您想运行测试套件：\n\n```bash\n# 安装 BATS 测试框架\nnpm install -g bats bats-support bats-assert\n\n# 运行所有测试（566 个测试）\nnpm test\n\n# 运行特定测试套件\nbats tests\u002Funit\u002Ftest_rate_limiting.bats\nbats tests\u002Funit\u002Ftest_exit_detection.bats\nbats tests\u002Funit\u002Ftest_json_parsing.bats\nbats tests\u002Funit\u002Ftest_cli_modern.bats\nbats tests\u002Funit\u002Ftest_cli_parsing.bats\nbats tests\u002Funit\u002Ftest_session_continuity.bats\nbats tests\u002Funit\u002Ftest_enable_core.bats\nbats tests\u002Funit\u002Ftest_task_sources.bats\nbats tests\u002Funit\u002Ftest_ralph_enable.bats\nbats tests\u002Funit\u002Ftest_wizard_utils.bats\nbats tests\u002Funit\u002Ftest_circuit_breaker_recovery.bats\nbats tests\u002Fintegration\u002Ftest_loop_execution.bats\nbats tests\u002Fintegration\u002Ftest_prd_import.bats\nbats tests\u002Fintegration\u002Ftest_project_setup.bats\nbats tests\u002Fintegration\u002Ftest_installation.bats\n\n# 运行错误检测和熔断器测试\n.\u002Ftests\u002Ftest_error_detection.sh\n.\u002Ftests\u002Ftest_stuck_loop_detection.sh\n```\n\n当前测试状态：\n- **566 个测试**，分布在 18 个测试文件中\n- **100% 通过率**（556\u002F556 通过）\n- 全面的单元和集成测试\n- 专门针对 JSON 解析、CLI 标志、熔断器、EXIT_SIGNAL 行为、启用向导以及安装流程的测试\n\n> **覆盖率说明**：使用 kcov 测量 Bash 代码覆盖率时，在追踪子进程执行方面存在根本性限制。测试通过率（100%）是质量门槛。详情请参阅 [bats-core#15](https:\u002F\u002Fgithub.com\u002Fbats-core\u002Fbats-core\u002Fissues\u002F15)。\n\n### 安装 tmux\n\n```bash\n# Ubuntu\u002FDebian\nsudo apt-get install tmux\n\n# macOS\nbrew install tmux\n\n# CentOS\u002FRHEL\nsudo yum install tmux\n```\n\n### 安装 GNU coreutils（macOS）\n\nRalph 使用 `timeout` 命令来实现执行超时。在 macOS 上，您需要安装 GNU coreutils：\n\n```bash\n# 安装 coreutils（提供 gtimeout）\nbrew install coreutils\n\n# 验证安装\ngtimeout --version\n```\n\nRalph 会自动检测并在 macOS 上使用 `gtimeout`。安装完成后无需额外配置。\n\n## 监控与调试\n\n### 实时仪表板\n\n```bash\n# 推荐使用集成的 tmux 监控\nralph --monitor\n\n# 在单独终端手动监控\nralph-monitor\n```\n\n实时显示：\n- 当前循环次数及状态\n- 已使用的 API 调用数与限额\n- 最近的日志条目\n- 速率限制倒计时\n\n**tmux 控制键：**\n- `Ctrl+B` 后按 `D` - 分离会话（Ralph 仍会继续运行）\n- `Ctrl+B` 后按 `←\u002F→` - 切换窗格\n- `tmux list-sessions` - 查看活动会话\n- `tmux attach -t \u003Csession-name>` - 重新连接到会话\n\n### 状态检查\n\n```bash\n# JSON 格式的状态输出\nralph --status\n\n# 手动检查日志\ntail -f .ralph\u002Flogs\u002Fralph.log\n```\n\n### 常见问题\n\n- **Ralph 在第一次循环中静默退出** - 可能是 Claude Code CLI 未安装或未添加到 PATH 中。Ralph 在启动时会验证命令是否存在，并显示安装说明。如果使用 npx，请在 `.ralphrc` 文件中添加 `CLAUDE_CODE_CMD=\"npx @anthropic-ai\u002Fclaude-code\"`。\n- **速率限制** - Ralph 会自动等待并显示倒计时。\n- **5 小时 API 限制** - Ralph 会检测并提示用户采取行动（等待或退出）。\n- **卡住的循环** - 检查 `fix_plan.md` 文件，查看是否有不明确或冲突的任务。\n- **提前退出** - 如果 Ralph 过早停止，请检查退出阈值。\n- **过早退出** - 检查 Claude 是否设置了 `EXIT_SIGNAL: false`（Ralph 现在会尊重此设置）。\n- **执行超时** - 对于复杂操作，可增加 `--timeout` 参数的值。\n- **缺少依赖项** - 确保已安装 Claude Code CLI 和 tmux。\n- **tmux 会话丢失** - 使用 `tmux list-sessions` 和 `tmux attach` 重新连接。\n- **会话过期** - 默认情况下，会话会在 24 小时后过期；使用 `--reset-session` 可以重新开始。\n- **timeout: command not found（macOS）** - 安装 GNU coreutils：`brew install coreutils`。\n- **权限被拒绝** - 当 Claude Code 被拒绝执行某些命令时，Ralph 会停止：\n  1. 编辑 `.ralphrc` 文件，将 `ALLOWED_TOOLS` 更新为包含所需工具。\n  2. 常见模式：`Bash(npm *)`、`Bash(git *)`、`Bash(pytest)`。\n  3. 更新 `.ralphrc` 后运行 `ralph --reset-session`。\n  4. 使用 `ralph --monitor` 重新启动。\n\n## 贡献\n\nRalph 正在积极寻求贡献者！我们正朝着 v1.0.0 版本努力，拥有清晰的优先级和详细的路线图。\n\n**请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取完整的贡献指南**，其中包括：\n- 入门和设置说明\n- 开发工作流程和提交规范\n- 代码风格指南\n- 测试要求（必须达到 100% 的通过率）\n- 拉取请求流程和代码审查指南\n- 质量标准和检查清单\n\n### 快速入门\n\n```bash\n# 分支并克隆\ngit clone https:\u002F\u002Fgithub.com\u002FYOUR_USERNAME\u002Fralph-claude-code.git\ncd ralph-claude-code\n\n# 安装依赖并运行测试\nnpm install\nnpm test  # 所有 566 个测试必须通过\n```\n\n### 优先贡献领域\n\n1. **测试实现** - 帮助扩展测试覆盖率\n2. **功能开发** - 日志轮转、试运行模式、指标\n3. **文档** - 教程、故障排除指南、示例\n4. **实际测试** - 使用 Ralph，报告 bug，分享反馈\n\n**每一份贡献都很重要** - 从修复错别字到实现重大功能！\n\n## 许可证\n\n本项目采用 MIT 许可证授权 - 详情请参阅 [LICENSE](LICENSE) 文件。\n\n## 致谢\n\n- 灵感来源于 Geoffrey Huntley 创建的 [Ralph 技术](https:\u002F\u002Fghuntley.com\u002Fralph\u002F)\n- 专为 Anthropic 的 [Claude Code](https:\u002F\u002Fclaude.ai\u002Fcode) 构建\n- 社区的反馈与贡献\n\n## 相关项目\n\n- [Claude Code](https:\u002F\u002Fclaude.ai\u002Fcode) - 驱动 Ralph 的 AI 编码助手\n- [Aider](https:\u002F\u002Fgithub.com\u002Fpaul-gauthier\u002Faider) - Ralph 技术的原始实现\n\n---\n\n## 命令参考\n\n### 安装命令（只需运行一次）\n```bash\n.\u002Finstall.sh              # 全局安装 Ralph\n.\u002Funinstall.sh            # 从系统中移除 Ralph（专用脚本）\n.\u002Finstall.sh uninstall    # 替代方案：从系统中移除 Ralph\n.\u002Finstall.sh --help       # 显示安装帮助\nralph-migrate             # 将现有项目迁移到 .ralph\u002F 结构\n```\n\n### Ralph 循环选项\n```bash\nralph [OPTIONS]\n  -h, --help              显示帮助信息\n  -c, --calls NUM         设置每小时最大调用次数（默认：100）\n  -p, --prompt FILE       设置提示文件（默认：PROMPT.md）\n  -s, --status            显示当前状态并退出\n  -m, --monitor           使用 tmux 会话和实时监控启动\n  -v, --verbose           在执行过程中显示详细进度更新\n  -l, --live              启用实时流输出（即时查看 Claude Code）\n  -t, --timeout MIN       设置 Claude Code 执行超时时间（1-120 分钟，默认：15 分钟）\n  --output-format FORMAT  设置输出格式：json（默认）或文本\n  --allowed-tools TOOLS   设置允许使用的 Claude 工具（默认：Write, Read, Edit, Bash(git *), Bash(npm *), Bash(pytest)）\n  --no-continue           禁用会话连续性（每次循环都从头开始）\n  --reset-circuit         重置断路器\n  --circuit-status        显示断路器状态\n  --auto-reset-circuit    启动时自动重置断路器（绕过冷却时间）\n  --reset-session         手动重置会话状态\n  -b, --backup            在每次循环前启用自动 git 备份分支（需要 git）\n  --rollback [BRANCH]     回滚到备份分支（若未指定，则列出可用分支）\n```\n\n### 项目相关命令（按项目）\n```bash\nralph-setup project-name     # 创建新的 Ralph 项目\nralph-enable                 # 在现有项目中启用 Ralph（交互式）\nralph-enable-ci              # 在现有项目中启用 Ralph（非交互式）\nralph-import prd.md project  # 将 PRD\u002F规格转换为 Ralph 项目\nralph --monitor              # 使用集成监控启动\nralph --status               # 检查当前循环状态\nralph --verbose              # 启用详细进度更新\nralph --timeout 30           # 设置 30 分钟的执行超时\nralph --calls 50             # 限制每小时 API 调用次数为 50 次\nralph --reset-session        # 手动重置会话状态\nralph --live                 # 启用实时流输出\nralph-monitor                # 手动监控仪表板\n```\n\n### tmux 会话管理\n```bash\ntmux list-sessions        # 查看活跃的 Ralph 会话\ntmux attach -t \u003Cname>     # 重新连接到已分离的会话\n# Ctrl+B then D           # 分离会话（保持运行）\n```\n\n---\n\n## 开发路线图\n\nRalph 目前正处于积极开发阶段，正朝着 v1.0.0 版本稳步前进。完整路线图请参阅 [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md)。\n\n### 当前状态：v0.11.5\n\n**已交付内容：**\n- 核心循环功能，具备智能退出检测\n- **双条件退出门控**（完成指标 + EXIT_SIGNAL）\n- 限流机制（每小时100次调用）及熔断模式\n- 具有语义理解能力的响应分析器\n- **556项全面测试**（100%通过率）\n- **直播输出模式**，可实时查看Claude Code代码\n- tmux集成与实时监控\n- 支持现代CLI JSON解析的PRD导入功能\n- 安装系统与项目模板\n- 现代化CLI命令，支持JSON输出\n- 使用GitHub Actions的CI\u002FCD流水线\n- **面向现有项目的交互式`ralph-enable`向导**\n- **`.ralphrc`配置文件支持**\n- 基于自动重置触发器的会话生命周期管理\n- 可配置超时时间的会话过期机制\n- 专用卸载脚本\n\n**测试覆盖率细分：**\n- 单元测试：477项（CLI解析、JSON处理、退出检测、限流与令牌预算、会话连续性、启用向导、直播流、熔断恢复、文件保护、完整性检查）\n- 集成测试：136项（循环执行、边缘场景、安装、项目初始化、PRD导入）\n- 测试文件：18个\n\n### 通往v1.0.0的道路（约4周）\n\n**增强测试**\n- 安装与设置工作流测试\n- tmux集成测试\n- 监控仪表盘测试\n\n**核心功能**\n- 日志轮转功能\n- 模拟运行模式\n\n**高级功能与优化**\n- 端到端测试\n- 最终文档编写与发布准备\n\n详细进度跟踪请参阅[IMPLEMENTATION_STATUS.md](IMPLEMENTATION_STATUS.md)。\n\n### 如何贡献\nRalph现正招募贡献者！完整指南请见[CONTRIBUTING.md](CONTRIBUTING.md)。优先领域：\n1. **测试实现** - 帮助扩展测试覆盖率（[查看计划](IMPLEMENTATION_PLAN.md)）\n2. **功能开发** - 日志轮转、模拟运行模式、指标收集\n3. **文档编写** - 使用示例、教程、故障排除指南\n4. **Bug报告** - 实际使用反馈及边缘场景\n\n---\n\n**准备好让AI构建你的项目了吗？** 从`.\u002Finstall.sh`开始，剩下的就交给Ralph吧！\n\n## 星标历史\n\n[![星标历史图表](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ffrankbria_ralph-claude-code_readme_f03ddc31ea18.png)](https:\u002F\u002Fwww.star-history.com\u002F#frankbria\u002Fralph-claude-code?type=date&legend=top-left)","# Ralph for Claude Code 快速上手指南\n\nRalph 是一个基于 Geoffrey Huntley 技术实现的自主 AI 开发循环工具，专为 **Claude Code** 设计。它能驱动 Claude Code 持续迭代改进你的项目，直到任务完成，并内置了智能退出检测、速率限制和熔断机制以防止无限循环或 API 滥用。\n\n## 环境准备\n\n在开始之前，请确保你的系统满足以下要求：\n\n*   **操作系统**: Linux, macOS (推荐), 或 WSL2 (Windows)。\n    *   *注：已修复 Bash 3.x 兼容性问题，支持更广泛的 Linux 发行版。*\n*   **核心依赖**:\n    *   **Node.js & npm**: 用于运行 Claude Code CLI。\n    *   **Claude Code CLI**: 必须已安装并配置好 API Key (`npm install -g @anthropic-ai\u002Fclaude-code`)。\n    *   **Git**: 用于版本控制和进度追踪。\n    *   **tmux** (可选但推荐): 用于实时监控面板 (`ralph --monitor`)。\n    *   **jq**: 用于处理 JSON 输出（通常系统自带或通过包管理器安装）。\n*   **API 配额**: 确保你的 Anthropic API 账户有足够的额度（默认限制为每小时 100 次调用，可配置）。\n\n## 安装步骤\n\nRalph 的安装分为两个阶段：**全局安装**（只需一次）和 **项目初始化**（每个项目一次）。\n\n### 第一阶段：全局安装 (One-time Install)\n\n将 Ralph 安装为全局命令，以便在任何目录下使用。\n\n```bash\n# 1. 克隆仓库\ngit clone https:\u002F\u002Fgithub.com\u002Ffrankbria\u002Fralph-claude-code.git\ncd ralph-claude-code\n\n# 2. 运行安装脚本\n.\u002Finstall.sh\n```\n\n安装完成后，`ralph`, `ralph-monitor`, `ralph-enable`, `ralph-import` 等命令将添加到你的系统 PATH 中。\n> **提示**: 安装成功后，你可以删除克隆的 `ralph-claude-code` 目录，不影响使用。如需卸载，运行 `.\u002Funinstall.sh` 或通过 curl 运行远程卸载脚本。\n\n### 第二阶段：项目初始化 (Per-Project Setup)\n\n根据你的项目状态，选择以下任一方式初始化：\n\n#### 方案 A：在现有项目中启用 (推荐)\n使用交互式向导自动检测项目类型（如 TypeScript, Python, Rust）并导入任务。\n\n```bash\ncd my-existing-project\n\n# 启动交互式向导 (自动识别框架并导入任务)\nralph-enable\n\n# 或者指定任务来源：\n# ralph-enable --from beads       # 从 beads 任务列表导入\n# ralph-enable --from github      # 从 GitHub Issues 导入\n# ralph-enable --from prd .\u002Fdocs\u002Frequirements.md # 从 PRD 文档导入\n```\n\n#### 方案 B：导入现有的需求文档 (PRD)\n将现有的需求文档转换为 Ralph 格式。\n\n```bash\n# 转换需求文档并创建项目结构\nralph-import my-requirements.md my-project\ncd my-project\n\n# (可选) 手动调整生成的 .ralph\u002F 目录下的配置文件\n```\n\n#### 方案 C：从零创建新项目\n创建一个带有最佳实践结构的空白 Ralph 项目。\n\n```bash\n# 创建新项目\nralph-setup my-awesome-project\ncd my-awesome-project\n\n# 手动编辑 .ralph\u002FPROMPT.md 定义项目目标\n# 手动编辑 .ralph\u002Fspecs\u002F 添加详细规格\n```\n\n## 基本使用\n\n初始化完成后，即可启动自主开发循环。\n\n### 启动开发循环 (带实时监控)\n\n这是最推荐的用法，它会启动一个 tmux 会话，同时运行 Ralph 循环和实时监控面板。\n\n```bash\n# 在项目根目录下运行\nralph --monitor\n```\n\n*   **左侧\u002F主窗口**: 显示 Claude Code 的实时执行日志。\n*   **监控面板**: 显示循环状态、进度条、API 调用计数和错误信息。\n\n### 分离模式 (无 tmux)\n\n如果你不想使用 tmux，可以在两个独立的终端窗口中分别运行：\n\n**终端 1 (执行循环):**\n```bash\nralph\n```\n\n**终端 2 (查看监控):**\n```bash\nralph-monitor\n```\n\n### 常用参数示例\n\n*   **断点续传**: 如果循环意外中断，使用 `--resume` 恢复上下文（防止会话劫持）。\n    ```bash\n    ralph --resume \u003Csession_id>\n    ```\n*   **实时流式输出**: 直接在当前终端查看 Claude Code 的实时输出。\n    ```bash\n    ralph --live\n    ```\n*   **指定允许的工具**: 限制 Claude Code 可使用的工具范围。\n    ```bash\n    ralph --allowed-tools \"Edit,Bash(npm *)\"\n    ```\n*   **单次执行不连续**: 运行一次后停止，不进入自动循环。\n    ```bash\n    ralph --no-continue\n    ```\n\n### 停止循环\n\nRalph 具备智能退出检测，当检测到 `EXIT_SIGNAL: true` 且完成指标满足时会自动停止。若需强制停止：\n*   在 tmux 模式中：按下 `Ctrl+b` 然后输入 `:kill-pane` 或直接关闭终端。\n*   在普通模式中：按下 `Ctrl+C`。","某全栈开发者正利用 Claude Code 重构一个遗留的电商订单模块，需要 AI 连续执行代码分析、单元测试编写及多轮修复，直至功能完全通过验证。\n\n### 没有 ralph-claude-code 时\n- **人工干预频繁**：开发者必须时刻守在终端旁，每次 Claude 完成一步就需手动输入指令让其继续，无法离开座位处理其他事务。\n- **无限循环风险**：当 AI 陷入逻辑死胡同或重复报错时，缺乏自动熔断机制，导致 API 调用在无人看管下疯狂消耗，产生高额账单。\n- **进度难以维持**：一旦遇到网络波动或会话超时，之前的上下文全部丢失，不得不重新描述需求，导致开发过程断断续续。\n- **退出判断模糊**：AI 常在任务未完成时误判为“结束”并提前退出，或者在已完成时还在无意义地空转，缺乏智能的完工检测。\n\n### 使用 ralph-claude-code 后\n- **全自动闭环开发**：启动 `ralph` 命令后，它会自动指挥 Claude Code 进行“编码 - 测试 - 修复”的迭代循环，直到检测到明确的完成信号才停止，开发者可安心下班。\n- **智能安全熔断**：内置的断路器和速率限制器能精准识别死循环与 API 限额，一旦检测到异常停滞或达到每小时 100 次调用上限，立即暂停并通知用户，杜绝资源浪费。\n- **会话无缝续传**：利用 `--resume` 标志和 24 小时会话保持机制，即使中途中断，也能完美恢复之前的上下文和进度，确保长周期任务不丢失状态。\n- **精准完工判定**：采用双重退出门控机制，只有当代码指标达标且收到明确退出信号时才会终止，既防止了过早放弃，也避免了无效空转。\n\nralph-claude-code 将原本需要人工全程盯守的碎片化交互，升级为安全、可控且真正自主的夜间自动化开发流程。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ffrankbria_ralph-claude-code_3fc4d7d4.png","frankbria","Frank Bria","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Ffrankbria_f3a651d7.jpg","I build AI systems and help investors understand them. 6k+ GitHub stars on agentic coding. Fintech background. Advisory via BSG.",null,"Phoenix, AZ","frank.bria@gmail.com","http:\u002F\u002Ffrankbria.com","https:\u002F\u002Fgithub.com\u002Ffrankbria",[83],{"name":84,"color":85,"percentage":86},"Shell","#89e051",100,8704,650,"2026-04-17T09:54:24","MIT","Linux, macOS","未说明",{"notes":94,"python":92,"dependencies":95},"该工具是一个基于 Shell 脚本的自动化包装器，用于驱动 Claude Code CLI 进行自主开发循环，而非本地运行的 AI 模型，因此无需 GPU 或特定 Python 环境。主要依赖已安装的 Claude Code CLI 和有效的 API 密钥。支持通过 'ralph-enable' 向导自动检测项目类型（如 TypeScript, Python, Rust, Go）。默认会话超时时间为 24 小时，API 调用限制默认为每小时 100 次。",[96,97,98,99,100],"Claude Code CLI","tmux (可选，用于实时监控)","jq (用于 JSON 处理)","Git","Bash (兼容 3.x 及以上，已修复 POSIX 兼容性)",[14,15,45,13],[103,104,105,106,107,108,109,110,111],"ai","ai-agent","ai-agents","ai-development","ai-development-tools","claude-code","claude-code-cli","development-tools","development-workflow","2026-03-27T02:49:30.150509","2026-04-18T02:20:34.929800",[115,120,125,130,134,138],{"id":116,"question_zh":117,"answer_zh":118,"source_url":119},38427,"Ralph 启动后立即退出或卡在\"Using modern CLI mode\"怎么办？","这通常是因为未全局安装 Claude Code CLI 或命令配置错误。Ralph 默认使用 `claude` 命令，如果未安装或使用了 `npx` 会导致后台进程启动失败。\n解决方案：\n1. 确保已全局安装：`npm install -g @anthropic-ai\u002Fclaude-code`\n2. 验证命令可用：在终端运行 `claude --version`\n3. 如需自定义命令，可在 `.ralphrc` 配置文件中设置 `CLAUDE_CODE_CMD` 变量指定正确的执行路径。","https:\u002F\u002Fgithub.com\u002Ffrankbria\u002Fralph-claude-code\u002Fissues\u002F97",{"id":121,"question_zh":122,"answer_zh":123,"source_url":124},38428,"如何将 Ralph 集成到现有的大型项目中而不弄乱根目录？","从 v0.10.0 版本开始，Ralph 支持将所有文件存储在 `.ralph\u002F` 子文件夹中，解决了根目录混乱的问题。\n对于现有项目的手动初始化步骤：\n1. 创建必要目录：`mkdir -p .ralph\u002F{specs\u002Fstdlib,examples,logs,docs\u002Fgenerated}`\n2. 复制模板文件：\n   - `cp ~\u002F.ralph\u002Ftemplates\u002FPROMPT.md .ralph\u002F`\n   - `cp ~\u002F.ralph\u002Ftemplates\u002Ffix_plan.md .ralph\u002F@fix_plan.md`\n   - `cp ~\u002F.ralph\u002Ftemplates\u002FAGENT.md .ralph\u002F@AGENT.md`\n注意：目前初始化不是幂等的，避免重复运行导致覆盖。未来版本将推出 `ralph-init` 命令以简化此过程。","https:\u002F\u002Fgithub.com\u002Ffrankbria\u002Fralph-claude-code\u002Fissues\u002F85",{"id":126,"question_zh":127,"answer_zh":128,"source_url":129},38429,"长时间运行后出现\"requires a valid session ID\"错误且循环失败怎么办？","这是由于旧版本中会话 ID 文件写入方式错误（使用追加 `>>` 而非覆盖 `>`），导致 `.ralph\u002F.claude_session_id` 文件累积了大量重复数据而损坏。\n解决方案：\n1. 删除损坏的文件：`rm .ralph\u002F.claude_session_id`\n2. 升级 Ralph 到最新版本（v2.3.2+），该版本已修复此问题，所有会话 ID 写入均改为覆盖模式。\n修复后无需再次手动删除，系统将自动管理会话文件。","https:\u002F\u002Fgithub.com\u002Ffrankbria\u002Fralph-claude-code\u002Fissues\u002F227",{"id":131,"question_zh":132,"answer_zh":133,"source_url":119},38430,"Ralph 运行时日志很少，如何确认它是否在工作或遵循退出条件？","Ralph 的详细调试日志默认可能未完全输出到 `.ralph\u002Flogs`，且 Claude Code 原生的流式输出可能被拦截。\n建议排查步骤：\n1. 检查 `.ralph\u002Fstatus.json` 文件查看当前状态和进度。\n2. 查看 `@fix_plan.md` 中的任务完成项计数（completed_items vs total_items）来确认进度。\n3. 确保 `.ralphrc` 中开启了详细日志模式（如果支持）。\n4. 观察进程是否占用 CPU，有时虽然终端无输出但后台仍在执行任务。如果长时间无变化且状态文件未更新，可能是遇到了上述的 CLI 启动失败问题。",{"id":135,"question_zh":136,"answer_zh":137,"source_url":124},38431,"如何在现有 Git 仓库中使用 Ralph 而不触发新的 git init？","在现有项目中，应避免让 Ralph 重新初始化 Git 仓库。\n变通方法：\n1. 手动创建 `.ralph` 目录结构而不是运行全自动初始化脚本。\n2. 修改配置文件或启动参数，明确指定工作目录为 `src\u002F` 或其他子目录，而不是根目录。\n3. 确保跳过任何包含 `git init` 的步骤。社区建议在配置中增加\"现有仓库\"模式选项，以便自动处理此类场景，目前需手动规避。",{"id":139,"question_zh":140,"answer_zh":141,"source_url":142},38432,"遇到权限问题导致 Ralph 无法执行任务时该如何解决？","虽然具体报错信息因环境而异，但通常涉及文件读写权限或执行权限。\n通用解决思路：\n1. 检查 `.ralph` 目录及其子目录的权限：`chmod -R u+w .ralph`\n2. 确保脚本文件具有执行权限：`chmod +x ralph_loop.sh`（如果是直接运行脚本）。\n3. 如果在 macOS 或 Linux 上遇到特定系统限制，可能需要调整安全设置或使用 `sudo`（谨慎使用）。\n4. 确认磁盘空间充足且文件系统未只读。\n若问题持续，请检查具体的错误日志片段以定位是哪个文件或操作被拒绝。","https:\u002F\u002Fgithub.com\u002Ffrankbria\u002Fralph-claude-code\u002Fissues\u002F178",[]]