Skip to content
ralph
AI-Agnostic Agentic Loops

ralph keeps going.

Reset the context. Feed the learnings. Watch it ship.

A CLI tool that runs productive AI coding agents for hours, not minutes.

terminal
$ ralph run "Add tests for all auth modules one module as a time"
↻ Loop 1: Found 12 auth modules, added tests for UserAuth...
↻ Loop 2: Added tests for SessionManager, TokenService...
↻ Loop 3: Added tests for OAuth, SAML providers...
✓ Done. 47 test files created. All passing.
Get Started How it works
Context Reset Fresh context window each iteration: Each loop iteration starts fresh. No accumulated confusion. The model reads your updated files and continues from where it left off.
State Persistence Learning is carry forward: Progress persists through your codebase. The AI reads vcs (git, jj etc) history, modified files, and test results to orient itself each iteration.
Exit Conditions Smart stopping when done: Define when to stop: tests passing, no more TODOs, specific markers. ralph knows when the job is done.
Tool Agnostic Works with Claude Code, OpenCode, other cli tool adapters coming soon.

Each Iteration

Orientation Read code state
→
Select Pick a task
→
Build Implement it
↓
Verify Run tests
→
Pass Mark complete
→
Document Save learnings
? All done?
→ Yes: Exit
↻ No: New loop

What is ralph?

Section titled “What is ralph?”

ralph is a CLI tool that runs AI coding agents in a loop. Instead of one-shot prompts that hit context limits and get confused, ralph resets the context window between iterations while preserving learnings through your codebase.

The technique is named after Ralph Wiggum from The Simpsons—embracing the philosophy of persistent iteration despite setbacks. “Me fail English? That’s unpossible!”

The Problem

Section titled “The Problem”

AI coding agents are powerful, but they have a critical limitation: context windows fill up.

As the model accumulates more context—tool calls, file reads, conversation history—it gets progressively worse at following instructions. Anthropic’s research confirms this: models perform best with fresh context.

Traditional approaches fail because:

  • One-shot prompts can’t handle complex multi-step tasks
  • Long conversations degrade model performance
  • Manual iteration is tedious and error-prone

The Solution

Section titled “The Solution”

ralph implements the Ralph Wiggum approach:

Terminal window
# This is ralph at its core
while ! done; do
  ai_agent "Complete the task. Check progress.txt for status."
done

Each iteration:

  1. Fresh context — Model starts clean
  2. Reads state — Checks files, git status, test results
  3. Does work — Makes progress on the task
  4. Updates state — Commits changes, updates progress markers
  5. Checks exit — Determines if work is complete

The loop continues until exit conditions are met—tests pass, no errors remain, or a completion marker is found.

Why “Ralph Wiggum”?

Section titled “Why “Ralph Wiggum”?”

The technique was coined by Geoffrey Huntley, who described it simply:

“Ralph is a Bash loop.”

The name captures the philosophy perfectly. Like Ralph Wiggum, the approach is:

  • Persistently optimistic — Keeps trying regardless of setbacks
  • Deterministically stubborn — Same prompt, different codebase state
  • Surprisingly effective — What seems simple produces remarkable results

Geoffrey ran a 3-month loop that built a complete programming language. YC hackathon teams shipped 6+ repos overnight for $297 in API costs.

Quick Start

Section titled “Quick Start”
Terminal window
# Install ralph
npm install -g @wiggumdev/ralph


# Run with your AI tool
ralph run --tool claude "Add comprehensive tests for all API endpoints"


# Or configure and go
ralph init
ralph run

Get Started →

Learn the Concepts