Introduction

Introduction to ralph

ralph is a CLI tool that orchestrates AI coding agents in iterative loops. It implements the “Ralph Wiggum” technique—resetting context windows between iterations while preserving state through your codebase.

The Core Insight

AI models have a fundamental limitation: as context accumulates, performance degrades. Anthropic’s research on long-running agents confirms what practitioners have observed:

When the context window fills up, the model gets dumb.

ralph solves this by:

1. Running your AI tool with a prompt
2. Letting it work until it tries to exit
3. Resetting the context (starting a new session)
4. Feeding the same prompt back
5. Repeating until done

The magic: the prompt stays the same, but the codebase changes. Each iteration, the model reads updated files, git history, and test results—learning from its own output.

Why “Ralph Wiggum”?

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

“Ralph is a Bash loop.”

The Philosophy

Like Ralph Wiggum from The Simpsons, this approach is deterministically stubborn in an undeterministic world. It keeps trying, keeps iterating, and—surprisingly often—succeeds.

The name captures something real about the technique:

• Simple to the point of seeming naive
• Persistently optimistic about outcomes
• Surprisingly effective in practice

What Makes ralph Different?

AI-Agnostic

ralph supports multiple AI coding tools:

• Claude Code — Anthropic’s official CLI (recommended)
• OpenCode — Open-source alternative with multi-provider support
• Gemini CLI — Google’s Gemini (under development)

Research-Backed

ralph implements best practices from Anthropic’s research on effective harnesses for long-running agents:

• Context window management — Fresh context each iteration
• State externalization — Progress lives in files, not conversation
• Explicit checkpoints — Clear markers of completed work
• Graceful exit conditions — Know when to stop

Production-Ready

ralph isn’t a toy. It’s been used to:

• Build complete programming languages (3-month loop)
• Ship multiple repositories overnight ($297 in API costs)
• Automate massive refactoring projects
• Generate comprehensive test suites

When to Use ralph

Large Refactors

Rename across hundreds of files. Update API contracts. Migrate frameworks.

Test Coverage

Add tests for all modules systematically. The loop continues until coverage targets are met.

Documentation

Generate docs for every function, class, and module. Consistent style throughout.

Migrations

Database schema changes. Framework upgrades. Language version bumps.

When NOT to Use ralph

ralph isn’t the right choice for everything:

• Quick one-off questions — Just use your AI tool directly
• Exploratory conversations — ralph is for task completion, not brainstorming
• Highly interactive work — If you need to make decisions constantly, work directly
• Simple tasks — If one prompt gets it done, one prompt is enough

Next Steps

Ready to dive in?

1. Installation — Get ralph set up
2. Quick Start — Your first loop
3. The Loop — Understand the core concept