Ralph for Claude Code

Ralph for Claude Code is an open-source shell-based tool that implements Geoffrey Huntley's "Ralph" technique for running Claude Code in continuous autonomous development cycles. Created by Frank Bria and licensed under MIT, it wraps the Claude Code CLI in a loop that iteratively improves a project until completion, with built-in safeguards against runaway API usage. The project has accumulated over 9,500 GitHub stars and is listed in the Awesome Claude Code collection.

What It Is

Ralph is a Bash-based automation layer that sits on top of the Claude Code CLI. Rather than running Claude Code once and reviewing the output manually, Ralph drives a loop: it reads your project's PROMPT.md and task list, invokes Claude Code, analyzes the response, tracks progress, and decides whether to continue or exit. The name comes from Geoffrey Huntley's original technique, itself named after Ralph Wiggum. The tool is installed globally once and then enabled per-project via a wizard or setup command.

How the Autonomous Loop Works

Each iteration of the Ralph loop follows a fixed cycle:

• Read instructions — loads .ralph/PROMPT.md and the prioritized task list in .ralph/fix_plan.md
• Execute Claude Code — invokes the claude CLI with configured tool permissions and session context
• Analyze response — a semantic response analyzer parses JSON or text output for completion signals
• Evaluate exit conditions — applies a dual-condition gate: both completion_indicators >= 2 AND Claude's explicit EXIT_SIGNAL: true must be present before the loop exits
• Repeat or exit — continues until the project is complete, a circuit breaker trips, or API limits are reached

The dual-condition exit gate is a key design decision: if Claude signals it is still working (EXIT_SIGNAL: false), Ralph continues even when heuristic completion indicators are high, preventing premature exits during productive iterations.

Safeguards and Reliability Features

Ralph includes several layers of protection against common failure modes:

• Rate limiting — configurable cap (default 100 calls/hour) with hourly reset and optional token-budget limit
• Circuit breaker — opens after repeated no-progress loops or identical errors; auto-recovers after a configurable cooldown (default 30 minutes)
• 5-hour API limit handling — three-layer detection (timeout guard → structured JSON rate_limit_event → filtered text fallback) with auto-wait in unattended mode
• Session expiration — sessions reset automatically after a configurable timeout (default 24 hours)
• Log rotation — ralph.log rotates at 10 MB, keeping four archived files
• Dry-run mode — simulates loop execution without making API calls

Deployment and Sandbox Options

Ralph runs locally by default, but supports two sandboxed execution modes for isolation:

• Docker sandbox (--sandbox docker) — Claude Code runs inside a container with configurable RAM, CPU, and network policy; credentials are passed via a 0600 env-file and cleaned up on exit
• E2B cloud sandbox (--sandbox e2b) — Claude Code runs in an E2B cloud environment; the project is uploaded at startup and changed files are synced back after each iteration, with cost tracking and budget controls

Both sandbox modes keep Ralph's loop, rate limiting, and monitoring on the host; only Claude's execution is isolated.

GitHub Issue Lifecycle Integration

Ralph can close the loop on the full GitHub workflow. By passing --github-issue <ref>, it can post progress comments during development, create a pull request on completion, close the source issue with a summary comment, add labels, and open follow-up issues for any TODO/FIXME markers introduced during the run. A batch queue (ralph-queue) supports processing multiple issues sequentially in priority and dependency order, with the queue state persisted to .ralph/queue.json across restarts.

Update: v0.11.5 — Community Bug Fixes

The current release is v0.11.5, tagged as active development with 784 tests at a 100% pass rate across 34 test files. Notable recent changes include:

• Fixed a false positive where a timeout (exit code 124) was misidentified as Claude's 5-hour API limit
• Unattended mode now auto-waits on API limit prompt timeout instead of exiting
• Fixed Bash 3.x compatibility by replacing ${,,} lowercase substitution with POSIX tr
• Added 8 new tests for API limit detection

The project roadmap targets v1.0.0 with remaining work focused on final documentation, supply-chain hardening for CI workflows, and real-world feedback integration. A multi-provider abstraction (multi-provider epic) is in progress to decouple Ralph from the claude CLI so any headless coding CLI (Codex, Gemini, OpenCode, Copilot) can drive the loop.