ralph-claude-code

Ralph is a shell-based wrapper around Claude Code, the AI coding tool, that lets it run in a continuous loop rather than stopping after each single task. The idea comes from a technique by Geoffrey Huntley: you give Ralph a set of project requirements, and it keeps calling Claude Code over and over, checking each time whether the work is actually done before moving on. The name comes from Ralph Wiggum, a character from The Simpsons.

The key problem Ralph tries to solve is that AI coding tools often declare success prematurely. Ralph addresses this with what it calls a dual-condition exit gate: before the loop stops, it requires Claude Code to emit both completion signals AND an explicit EXIT_SIGNAL flag. One condition alone is not enough to end the run. This prevents the loop from quitting early based on a vague "looks done" response.

Ralph also handles the practical friction of running AI tooling at scale. It tracks API call counts and enforces an hourly rate limit to avoid burning through your quota. It has a circuit breaker that detects when the loop is stuck, not making progress, or hitting repeated errors. For sessions running overnight or unattended, it includes a configurable timeout (default 24 hours) after which it resets the session rather than looping forever.

Setup works through either a ralph-enable wizard or a ralph-setup script. Both produce a .ralphrc config file in your project that stores things like which tools Claude Code is allowed to use and what your task source is. Tasks can come from a product requirements document, GitHub Issues, or a task manager called Beads. Once configured, you run ralph in any terminal and it takes over from there.

The project is under active development at version 0.11.5, with 566 tests and a stated goal of reaching v1.0 in roughly four weeks from the time of writing. It is open source under an MIT license. The full README is longer than what was shown.