frankbria /ralph-claude-code
Autonomous AI development loop for Claude Code with intelligent exit detection
★ 9,734⑂ 728👁 42⑃ 196● 196▤ 0
+2
Daily
9,734
stars
728
forks
42
watchers
196
prs
196
issues
0
releases
README
Ralph for Claude Code !Version !Tests Autonomous AI development loop with intelligent exit detection and rate limiting Ralph is an implementation of the Geoffrey Huntley's technique for Claude Code that enables continuous autonomous development cycles he named after Ralph Wiggum. 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. Install once, use everywhere - Ralph becomes a global command available in any directory. Project Status Version: v0.11.5 - Active Development Core Features: Working and tested Test Coverage: 784 tests, 100% pass rate What's Working Now - Autonomous development loops with intelligent exit detection - Dual-condition exit gate: Requires BOTH completion indicators AND explicit EXIT_SIGNAL - Rate limiting with hourly reset (100 calls/hour, configurable) - Circuit breaker with advanced error detection (prevents runaway loops) - Response analyzer with semantic understanding and two-stage error filtering - JSON output format support with automatic fallback to text parsing - Session continuity with --resume flag for context preservation (no session hijacking) - Session expiration with configurable timeout (default: 24 hours) - Modern CLI flags: --output-format, --allowed-tools, --no-continue - Interactive project enablement with ralph-enable wizard - .ralphrc configuration file for project settings - Live streaming output with --live flag for real-time Claude Code visibility - Log rotation: ralph.log rotates at 10MB, keeping 4 archived files - Dry-run mode (--dry-run) to simulate loops without API calls - Metrics tracking with ralph-stats analytics command (JSON Lines per-loop metrics) - Desktop notifications (--notify) for key loop events (macOS/Linux/terminal-bell) - Automatic git backup branches (--backup) with --rollback restore - Multi-line error matching for accurate stuck loop detection - 5-hour API limit handling with user prompts - tmux integration for live monitoring - PRD import functionality - GitHub issue import: ralph-import --github-issue plus metadata filters (labels, title, assignee, milestone, state) with first/interactive/priority selection and --dry-run preview - CI/CD pipeline with GitHub Actions - Dedicated uninstall script for clean removal Recent Improvements Unreleased - Security: .ralphrc is parsed as data (346) - .ralphrc is no longer executed with source: only KEY=VALUE lines for known keys are applied, with literal values. Shell syntax ($VAR, $(...), chained commands) is rejected with a warning — breaking for .ralphrc files that relied on it - CLAUDE_CODE_CMD, RALPH_SHELL_INIT_FILE, SANDBOX_DOCKER_IMAGE, SANDBOX_E2B_TEMPLATE and SANDBOX_DOCKER_NETWORK (no host) accept only stock values from .ralphrc; set custom values as environment variables (or --sandbox- flags). Applies to ralph, ralph-import and ralph-queue. See docs/CLI_OPTIONS.md v0.11.5
Top issues
#327[P8.1] Recompile triage-incoming-issues.lock.yml to pick up gh-aw v0.79.8 + checkout v6.0.33 comments · 2026-06-15#394[P8.8] SIGTERM/Ctrl-C in --live/--monitor mode waits for the running Claude call1 comments · 2026-11-04#388[P8.6] E2B sandbox: remaining RALPH_DIR edge cases (symlink to outside, cwd /, outside-workspace mapping)1 comments · 2026-10-10#384[P8.5] GLM review check fails on every fork PR (no secrets) — skip it for forks1 comments · 2026-10-09#372[P8.3] Coverage job reports green while 43 tests fail under kcov (relative LD_PRELOAD path)1 comments · 2026-10-07#367[P0.0] Ralph's next chapter: a companion to native /goal1 comments · 2026-10-06#358[P8.2] [aw] Issue Triage Assistant failed0 comments · 2026-09-24