{"id":31581052,"url":"https://github.com/frankbria/ralph-claude-code","last_synced_at":"2026-04-16T00:31:53.511Z","repository":{"id":311947146,"uuid":"1045721921","full_name":"frankbria/ralph-claude-code","owner":"frankbria","description":"Autonomous AI development loop for Claude Code with intelligent exit detection","archived":false,"fork":false,"pushed_at":"2026-04-02T02:43:40.000Z","size":477,"stargazers_count":8351,"open_issues_count":34,"forks_count":612,"subscribers_count":42,"default_branch":"main","last_synced_at":"2026-04-02T13:05:28.223Z","etag":null,"topics":["ai","ai-agent","ai-agents","ai-development","ai-development-tools","claude-code","claude-code-cli","development-tools","development-workflow"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/frankbria.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-27T16:03:45.000Z","updated_at":"2026-04-02T12:38:18.000Z","dependencies_parsed_at":"2025-08-28T01:28:48.211Z","dependency_job_id":"a3377937-bdb4-48eb-b54f-8c779c8805a5","html_url":"https://github.com/frankbria/ralph-claude-code","commit_stats":null,"previous_names":["frankbria/ralph-claude-code"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/frankbria/ralph-claude-code","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frankbria%2Fralph-claude-code","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frankbria%2Fralph-claude-code/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frankbria%2Fralph-claude-code/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frankbria%2Fralph-claude-code/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/frankbria","download_url":"https://codeload.github.com/frankbria/ralph-claude-code/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frankbria%2Fralph-claude-code/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31866268,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"ssl_error","status_checked_at":"2026-04-15T15:24:39.138Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agent","ai-agents","ai-development","ai-development-tools","claude-code","claude-code-cli","development-tools","development-workflow"],"created_at":"2025-10-05T21:52:32.357Z","updated_at":"2026-04-16T00:31:53.479Z","avatar_url":"https://github.com/frankbria.png","language":"Shell","readme":"# Ralph for Claude Code\n\n[![CI](https://github.com/frankbria/ralph-claude-code/actions/workflows/test.yml/badge.svg)](https://github.com/frankbria/ralph-claude-code/actions/workflows/test.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n![Version](https://img.shields.io/badge/version-0.11.5-blue)\n![Tests](https://img.shields.io/badge/tests-556%20passing-green)\n[![GitHub Issues](https://img.shields.io/github/issues/frankbria/ralph-claude-code)](https://github.com/frankbria/ralph-claude-code/issues)\n[![Mentioned in Awesome Claude Code](https://awesome.re/mentioned-badge.svg)](https://github.com/hesreallyhim/awesome-claude-code)\n[![Follow on X](https://img.shields.io/twitter/follow/FrankBria18044?style=social)](https://x.com/FrankBria18044)\n\n\u003e **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://ghuntley.com/ralph/). 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/hour, 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/CD 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 \u0026 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\u003e` 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 \u0026 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/automation\n- New library components: `enable_core.sh`, `wizard_utils.sh`, `task_sources.sh`\n\n**v0.10.1 - Bug Fixes \u0026 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/ Subfolder Structure (BREAKING CHANGE)**\n- **Breaking**: Moved all Ralph-specific files to `.ralph/` subfolder\n- Project root stays clean: only `src/`, `README.md`, and user files remain\n- Added `ralph-migrate` command for upgrading existing projects\n\n\u003cdetails\u003e\n\u003csummary\u003eEarlier versions (v0.9.x)\u003c/summary\u003e\n\n**v0.9.9 - EXIT_SIGNAL Gate \u0026 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 \u0026 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/details\u003e\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/CD 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| ./install.sh    |    -\u003e    | 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://github.com/frankbria/ralph-claude-code.git\ncd ralph-claude-code\n./install.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\u003e **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 ./docs/requirements.md\n\n# Start autonomous development\nralph --monitor\n```\n\n#### Option B: Import Existing PRD/Specifications\n```bash\n# Convert existing PRD/specs to Ralph format\nralph-import my-requirements.md my-project\ncd my-project\n\n# Review and adjust the generated files:\n# - .ralph/PROMPT.md (Ralph instructions)\n# - .ralph/fix_plan.md (task priorities)\n# - .ralph/specs/requirements.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/PROMPT.md with your project goals\n# Edit .ralph/specs/ with detailed specifications\n# Edit .ralph/fix_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./uninstall.sh\n\n# Or if you deleted the repo, download and run:\ncurl -sL https://raw.githubusercontent.com/frankbria/ralph-claude-code/main/uninstall.sh | bash\n```\n\n## Understanding Ralph Files\n\nAfter running `ralph-enable` or `ralph-import`, you'll have a `.ralph/` 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/PROMPT.md` | Yes (smart defaults) | **Review \u0026 customize** project goals and principles |\n| `.ralph/fix_plan.md` | Yes (can import tasks) | **Add/modify** specific implementation tasks |\n| `.ralph/AGENT.md` | Yes (detects build commands) | Rarely edit (auto-maintained by Ralph) |\n| `.ralph/specs/` | Empty directory | Add files when PROMPT.md isn't detailed enough |\n| `.ralph/specs/stdlib/` | 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/ (detailed requirements when needed)\n    ↓\nfix_plan.md (specific tasks Ralph executes)\n    ↓\nAGENT.md (build/test commands - auto-maintained)\n```\n\n### When to Use specs/\n\n- **Simple projects**: PROMPT.md + fix_plan.md is usually enough\n- **Complex features**: Add specs/feature-name.md for detailed requirements\n- **Team conventions**: Add specs/stdlib/convention-name.md for reusable patterns\n\nSee the [User Guide](docs/user-guide/) for detailed explanations and the [examples/](examples/) 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 \u003e= 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/fix_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/` directory and `.ralphrc` configuration\n5. **Verifies Setup** - Confirms all files are created correctly\n\n**Non-interactive mode for CI/automation:**\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/PROMPT.md** - Converted into Ralph development instructions\n- **.ralph/fix_plan.md** - Requirements broken down into prioritized tasks\n- **.ralph/specs/requirements.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/`\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/claude-code\"  # Alternative: use npx\n\n# Shell init file — source before running claude (useful for zsh/fish users\n# whose PATH or env vars are only set in their shell's init file)\n#RALPH_SHELL_INIT_FILE=\"~/.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 \u0026 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/live.log\ntail -f .ralph/live.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/.ralph_session              # View current session file\ncat .ralph/.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 / 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/.ralph_session` with a configurable expiration (default: 24 hours). The last 50 session transitions are logged to `.ralph/.ralph_session_history` for debugging.\n\n### Exit Thresholds\n\nModify these variables in `~/.ralph/ralph_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 \u003e70%\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| \u003e= 2 | `true` | **Exit** (\"project_complete\") |\n| \u003e= 2 | `false` | **Continue** (Claude still working) |\n| \u003e= 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/` subfolder for configuration:\n\n```\nmy-project/\n├── .ralph/                 # 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/              # Project specifications and requirements\n│   │   └── stdlib/         # Standard library specifications\n│   ├── examples/           # Usage examples and test cases\n│   ├── logs/               # Ralph execution logs\n│   └── docs/generated/     # Auto-generated documentation\n├── .ralphrc                # Ralph configuration file (tool permissions, settings)\n└── src/                    # Source code implementation (at project root)\n```\n\n\u003e **Migration**: If you have existing Ralph projects using the old flat structure, run `ralph-migrate` to automatically move files to the `.ralph/` subfolder.\n\n## Best Practices\n\n### Writing Effective Prompts\n\n1. **Be Specific** - Clear requirements lead to better results\n2. **Prioritize** - Use `.ralph/fix_plan.md` to guide Ralph's focus\n3. **Set Boundaries** - Define what's in/out of scope\n4. **Include Examples** - Show expected inputs/outputs\n\n### Project Specifications\n\n- Place detailed requirements in `.ralph/specs/`\n- Use `.ralph/fix_plan.md` for prioritized task tracking\n- Keep `.ralph/AGENT.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/logs/` for detailed execution history\n- Monitor `.ralph/status.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/claude-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/unit/test_rate_limiting.bats\nbats tests/unit/test_exit_detection.bats\nbats tests/unit/test_json_parsing.bats\nbats tests/unit/test_cli_modern.bats\nbats tests/unit/test_cli_parsing.bats\nbats tests/unit/test_session_continuity.bats\nbats tests/unit/test_enable_core.bats\nbats tests/unit/test_task_sources.bats\nbats tests/unit/test_ralph_enable.bats\nbats tests/unit/test_wizard_utils.bats\nbats tests/unit/test_circuit_breaker_recovery.bats\nbats tests/integration/test_loop_execution.bats\nbats tests/integration/test_prd_import.bats\nbats tests/integration/test_project_setup.bats\nbats tests/integration/test_installation.bats\n\n# Run error detection and circuit breaker tests\n./tests/test_error_detection.sh\n./tests/test_stuck_loop_detection.sh\n```\n\nCurrent test status:\n- **566 tests** across 18 test files\n- **100% pass rate** (556/556 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\u003e **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://github.com/bats-core/bats-core/issues/15) for details.\n\n### Installing tmux\n\n```bash\n# Ubuntu/Debian\nsudo apt-get install tmux\n\n# macOS\nbrew install tmux\n\n# CentOS/RHEL\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 `←/→` - Switch between panes\n- `tmux list-sessions` - View active sessions\n- `tmux attach -t \u003csession-name\u003e` - Reattach to session\n\n### Status Checking\n\n```bash\n# JSON status output\nralph --status\n\n# Manual log inspection\ntail -f .ralph/logs/ralph.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/claude-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://github.com/YOUR_USERNAME/ralph-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://ghuntley.com/ralph/) created by Geoffrey Huntley\n- Built for [Claude Code](https://claude.ai/code) by Anthropic\n- Community feedback and contributions\n\n## Related Projects\n\n- [Claude Code](https://claude.ai/code) - The AI coding assistant that powers Ralph\n- [Aider](https://github.com/paul-gauthier/aider) - Original Ralph technique implementation\n\n---\n\n## Command Reference\n\n### Installation Commands (Run Once)\n```bash\n./install.sh              # Install Ralph globally\n./uninstall.sh            # Remove Ralph from system (dedicated script)\n./install.sh uninstall    # Alternative: Remove Ralph from system\n./install.sh --help       # Show installation help\nralph-migrate             # Migrate existing project to .ralph/ 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/specs 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\u003e     # 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/hour) 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/CD 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 \u0026 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 `./install.sh` and let Ralph take it from there!\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=frankbria/ralph-claude-code\u0026type=date\u0026legend=top-left)](https://www.star-history.com/#frankbria/ralph-claude-code\u0026type=date\u0026legend=top-left)\n","funding_links":[],"categories":["Workflows \u0026 Knowledge Guides 🧠","Repos","Shell","Personal Assistants \u0026 Conversational Agents","Implementations","🤖 AI \u0026 Machine Learning","Autonomous Loop Runners","Agent Orchestration","Productivity Tools","Frameworks \u0026 Libraries","Other"],"sub_categories":["Ralph Wiggum","Chatbots","Claude Code Plugins","Autonomous Development","Copilot Extensions \u0026 Alternatives"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrankbria%2Fralph-claude-code","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrankbria%2Fralph-claude-code","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrankbria%2Fralph-claude-code/lists"}