git404hub

what is ralph-claude-code fr?

frankbria/ralph-claude-code — explained in plain English

Analysis updated 2026-06-24

9,117ShellAudience · developerComplexity · 2/5LicenseSetup · moderate

tl;dr

Ralph is a shell script that runs Claude Code in a continuous loop, checking after each pass whether the task is truly finished before stopping, with rate limiting, a circuit breaker, and a two-signal exit gate to prevent premature quitting.

vibe map

mindmap
  root((repo))
    What it does
      Loops Claude Code
      Checks completion
      Dual-condition gate
    Safety features
      Rate limiting
      Circuit breaker
      Session timeout
    Task sources
      Requirements doc
      GitHub Issues
      Beads task manager
    Setup
      ralphrc config
      Claude Code needed

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

what do people make with this?

VIBE 1

Run Claude Code unattended overnight on a large feature or task list without it stopping prematurely.

VIBE 2

Drive a multi-step coding project from a product requirements document or GitHub Issues, with Claude Code working through tasks automatically.

VIBE 3

Set a per-hour API call budget to avoid burning through your Claude quota in a single unattended session.

what's the stack?

ShellClaude Code

how it stacks up fr

frankbria/ralph-claude-codephusion/baseimage-dockerkylemanna/docker-openvpn
Stars9,1179,0999,078
LanguageShellShellShell
Setup difficultymoderateeasymoderate
Complexity2/53/53/5
Audiencedeveloperops devopsops devops

Figures from each repo's GitHub metadata at analysis time.

how do i run it?

Difficulty · moderate time til it works · 30min

Requires Claude Code installed and a valid Anthropic API key already configured on your machine.

MIT license, use freely for any purpose, including commercial use, as long as you keep the copyright notice.

in plain english

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.

prompts (copy fr)

prompt 1
Help me write a product requirements document I can give to Ralph so it drives Claude Code to build a simple CRUD web app.
prompt 2
Show me how to configure .ralphrc to allow specific Claude Code tools and set an hourly API rate limit.
prompt 3
Walk me through setting up Ralph to pull tasks from GitHub Issues and have Claude Code work through them one by one.
prompt 4
Explain how Ralph's dual-condition exit gate works and show me exactly what I need to add to a prompt so Ralph knows the task is truly done.
prompt 5
Help me configure Ralph's circuit breaker and timeout settings so it stops safely if Claude Code gets stuck in a loop.

Frequently asked questions

what is ralph-claude-code fr?

Ralph is a shell script that runs Claude Code in a continuous loop, checking after each pass whether the task is truly finished before stopping, with rate limiting, a circuit breaker, and a two-signal exit gate to prevent premature quitting.

What language is ralph-claude-code written in?

Mainly Shell. The stack also includes Shell, Claude Code.

What license does ralph-claude-code use?

MIT license, use freely for any purpose, including commercial use, as long as you keep the copyright notice.

How hard is ralph-claude-code to set up?

Setup difficulty is rated moderate, with roughly 30min to a first successful run.

Who is ralph-claude-code for?

Mainly developer.

peek the repo → explain another one

This repo across BitVibe Labs

double-check against the repo, no cap.