Ralph for Claude Code is an autonomous AI development loop implementation based on Geoffrey Huntley's technique that enables Claude Code to iteratively improve projects with built-in safeguards against infinite loops and API overuse. The repository is written in Shell and classified across multiple domains including AI, Large Language Models, Prompt Engineering, Policy Analysis, and Decision Support. The project maintains active development status at version v0.11.5 with 784 tests achieving 100% pass rate.
The core functionality centers on autonomous development cycles where Claude Code continuously works on project improvements until completion. The system implements a dual-condition exit gate requiring both completion indicators and an explicit EXIT_SIGNAL to prevent premature termination. Rate limiting is enforced at 100 calls per hour with configurable thresholds, and a circuit breaker with advanced error detection prevents runaway loops. The response analyzer provides semantic understanding with two-stage error filtering, and the system supports JSON output format with automatic fallback to text parsing for robustness.
Session management features include context preservation across loop iterations through a resume flag that prevents session hijacking, configurable session expiration with a default 24-hour timeout, and automatic session reset triggers. The CLI provides modern flags including output-format selection, allowed-tools specification, and a no-continue option. An interactive project enablement wizard called ralph-enable guides users through setup with environment detection, task source selection, and configuration generation. Projects can be configured via a .ralphrc configuration file for persistent settings.
Monitoring and visibility features include live streaming output with the --live flag for real-time Claude Code visibility, log rotation that maintains a 10MB primary log with four archived files, dry-run mode for simulating loops without API calls, and metrics tracking through the ralph-stats analytics command that outputs JSON Lines per-loop metrics. Desktop notifications alert users to key loop events on macOS, Linux, and terminal environments. The system handles the 5-hour API limit through three-layer detection combining timeout guards, structural JSON parsing, and filtered text fallback, with automatic waiting in unattended mode.
Advanced features include automatic git backup branches with rollback restoration capability, tmux integration for live monitoring, PRD import functionality, and GitHub issue import with metadata filtering by labels, title, assignee, milestone, and state. The system supports multiple task sources including beads, GitHub Issues, and PRD documents. Docker sandbox execution provides isolated container runs with resource limits and network policies, while E2B cloud sandbox execution offers file synchronization, session recovery, and cost tracking.
GitGenius activity data shows the repository has processed 172 issues and pull requests with a median response latency of 0.1 hours and mean latency of 38.9 hours. The most active labels tracked are enhancement with 80 occurrences, bug with 39, and priority P1 with 16. Primary contributor frankbria generated 546 tracked events, with wtthornton contributing 45 events and bbhxwl contributing 4 events. The repository shares overlapping contributors with github/gh-aw, solo-io/gloo, and longhorn/longhorn.
Recent development focused on bug fixes and compatibility improvements. Version v0.11.5 addressed API limit false positives where timeout exit code 124 was misidentified as API limits, implemented three-layer API limit detection, fixed bash 3.x compatibility by replacing lowercase substitution with POSIX tr, and added eight new tests. Version v0.11.4 fixed progress detection to count git commits within loops, corrected checkbox regex to avoid counting date entries, resolved session hijacking vulnerabilities, and fixed EXIT_SIGNAL override behavior. The roadmap indicates ongoing work toward version 1.0 with expanded test coverage and multi-provider agent abstraction to decouple Ralph from Claude so other headless coding CLIs can drive the loop.
