The Ralph Wiggum Loop: How a Bash While-True Became an AI Development Pattern

In July 2025, developer Geoffrey Huntley published a post titled "Ralph Wiggum as a software engineer" that would change how people use Claude Code. The core idea was a one-liner: wrap Claude Code in a bash loop, pipe in a prompt file, and let it run. When one session finishes, another starts immediately -- reading the same codebase, the same instructions, picking up where the last left off through files on disk.

while :; do cat PROMPT.md | claude-code ; done

(Note: claude-code is Huntley's shell alias. The official CLI command is claude.)

Huntley named it after Ralph Wiggum from The Simpsons -- the kid who keeps going despite every setback. His description of the technique: Ralph builds playgrounds, but he comes home bruised because he fell off the slide. So you tune Ralph by adding a sign next to the slide saying "SLIDE DOWN, DON'T JUMP, LOOK AROUND." Eventually Ralph reads the signs and stops falling. When all Ralph thinks about is the signs, you get a new Ralph that doesn't feel defective at all.

The tuning metaphor is central. Huntley describes Ralph as "deterministically bad in an undeterministic world" -- the defects are identifiable and resolvable through prompt engineering. Each time Ralph does something bad, Ralph gets tuned, like a guitar.

A Y Combinator hackathon team put Ralph to the test and shipped 6 repositories overnight. The Register and VentureBeat covered it. Huntley taught the technique to engineers in San Francisco; one used it on their next contract and walked away with, in Huntley's words, "the wildest ROI."

Installing the Plugin

First, add Anthropic's plugin marketplace:

/plugin marketplace add anthropics/claude-code

Then install the plugin:

/plugin install ralph-wiggum@claude-code-plugins

Once installed, you get three slash commands: /ralph-loop, /cancel-ralph, and /help.

How the Official Plugin Works

Anthropic engineers Daisy Hollman and Boris Cherny formalized the pattern into a Claude Code plugin. Instead of an external bash loop restarting the process, the plugin uses Claude Code's stop hook mechanism to prevent the session from ending.

The flow works like this: a user invokes /ralph-loop with a task description and an optional --max-iterations flag. The command runs a setup script that creates a state file at .claude/ralph-loop.local.md containing the prompt, iteration count, and maximum iterations in YAML frontmatter. Claude then begins working on the task.

When Claude finishes what it thinks is a complete unit of work and attempts to exit, the stop hook intercepts the exit. The hook reads Claude's transcript from stdin and checks for a <promise> tag -- a signal that Claude believes all work is genuinely done. If no promise is found and the iteration limit hasn't been reached, the hook returns exit code 2, which blocks the exit and re-feeds the prompt. Claude wakes up, re-reads the state file, and continues.

A typical invocation:

/ralph-loop Build a REST API with CRUD endpoints for a user model.
Run the test suite after each change. --max-iterations 20

The <promise> mechanism is the key design choice. Claude must explicitly declare completion by outputting a promise tag in its response. This prevents premature termination -- Claude can't just stop talking and have the session end. It must affirmatively state the work is done.

Plugin File Structure

The plugin organizes into three directories matching Claude Code's plugin conventions:

.claude-plugin/
├── commands/
│   ├── ralph-loop.md       # /ralph-loop slash command
│   ├── cancel-ralph.md     # /cancel-ralph to stop the loop
│   └── help.md             # /help for usage info
├── hooks/
│   └── stop-hook.sh        # intercepts session exit
└── scripts/
    └── setup-ralph-loop.sh # creates state file

The state file at .claude/ralph-loop.local.md uses YAML frontmatter to track loop state:

---
iteration: 3
max_iterations: 50
prompt: "Build a REST API with CRUD endpoints..."
promise: null
---

Three slash commands control the loop: /ralph-loop starts it, /cancel-ralph removes the state file to let the next exit succeed, and /help shows usage documentation.

The Stop Hook Decision Logic

The stop hook script (stop-hook.sh) receives Claude's transcript on stdin every time Claude attempts to exit. Its decision tree is straightforward:

1. State file exists? If no .claude/ralph-loop.local.md file is found, the loop isn't active. Allow exit normally (code 0).

2. Promise in output? The hook greps the transcript for <promise> tags. If found, Claude has declared the work complete. Allow exit (code 0).

3. Max iterations reached? Compare the current iteration counter against the configured maximum. If reached, allow exit with a warning (code 0).

4. Otherwise: block exit. Increment the iteration counter in the state file and return exit code 2. Claude Code interprets code 2 as "do not exit" and re-feeds the prompt from the state file.

The elegance is in the exit codes. Claude Code's hook system uses a simple convention: 0 means proceed, 2 means block. No IPC, no sockets, no daemon process. Just a shell script reading stdin and returning an integer.

The Context Window Debate

Here's where the original bash loop and the official plugin diverge architecturally, and where the community disagrees.

The original while :; loop starts a new process each iteration. Each Claude Code invocation gets a fresh context window. It sees the codebase, the git history, and the prompt file -- nothing else. No memory of what it tried before, no accumulated conversation. If the previous iteration wrote buggy code, this iteration discovers it the same way a new developer would: by reading the files and running the tests.

The plugin keeps a single session alive. Conversation history accumulates across iterations. Claude remembers what it tried, what failed, what it decided. The context window fills up over time.

HumanLayer's analysis argued that the plugin misses the core insight of Huntley's original pattern. The value wasn't just in looping -- it was in doing small bits of work in independent context windows. Each fresh process avoids the accumulated confusion that comes from long conversations. A model that has been debugging for 30 iterations carries cognitive baggage from every failed approach.

The trade-off:

Aspect	Bash Loop	Stop Hook Plugin
Context	Fresh each iteration	Accumulated history
Memory	No prior conversation	Full conversation retained
Cost per iteration	Higher (full prompt each time)	Lower (incremental)
Stuck behavior	Clean restart	May repeat failed approaches
Coordination	Via files on disk	Via conversation + files

Community forks have explored middle ground. Some implementations periodically clear conversation history while keeping the loop alive. Others use the bash loop but with structured state files that persist learnings across iterations without carrying full conversation context.

Everything Is a Loop

In January 2026, Huntley published a follow-up: "everything is a ralph loop." The argument goes beyond a coding trick. Standard software practice builds vertically, brick by brick, like Jenga. Huntley's claim is that with AI agents, everything becomes a loop instead.

Ralph isn't just forward mode (building autonomously) or reverse mode (clean rooming). It's a mindset that these computers can be programmed through loops. Software becomes clay on the pottery wheel -- if something isn't right, throw it back on the wheel.

Huntley is explicit about Ralph being monolithic: a single process, a single repository, one task per loop. He pushes back against the multi-agent trend: consider what microservices would look like if the microservices themselves are non-deterministic. Ralph scales vertically, not horizontally.

The operator's job shifts to watching the loop. When you see a failure domain, you put on your engineering hat and resolve it so it never happens again. In practice this means tuning the prompt, adding guardrails, or restructuring the task -- not writing the code yourself.

Case Study: CURSED

The most striking demonstration of Ralph running at scale is CURSED, a Gen Z programming language that Huntley built by running Claude in a loop for three months.

The prompt was simple: make a programming language like Go, but with all lexical keywords swapped to Gen Z slang. Claude was given autonomy to implement whatever it deemed appropriate. The result is a compiled language with LLVM backend that produces binaries on macOS, Linux, and Windows.

The keyword mapping:

Go	CURSED	Meaning
func	slay	function declaration
var	sus	variable
import	yeet	import
package	vibe	package
return	damn	return
for	bestie	for loop
if	ready	conditional
true	based	boolean true
false	cringe	boolean false
*T	ඞT	pointer (Amogus)
//	fr fr	line comment

Comments use fr fr for single-line and no cap...on god for block comments. Pointers use the Among Us character ඞ.

The language has a compiler with interpreted and compiled modes, half-completed editor extensions for VSCode/Emacs/Vim, a Treesitter grammar, and a standard library. Huntley's position: any remaining problems can be solved by running more Ralph loops, operated by people who understand compilers and shape the output through prompts drawn from that expertise.

The project's stated success criterion: ending up in the Stack Overflow developer survey as either the most loved or most hated language. The next goal is bootstrapping -- rewriting the CURSED compiler in CURSED itself.

Writing Effective Ralph Prompts

The loop is only as good as the prompt driving it. The best prompts share common traits: they define measurable completion criteria, break work into phases, and include verification commands.

Bad prompt:

Make the app better. Fix any bugs you find
and add features that seem useful.

No exit condition, no verification, no scope boundary. This will loop until max iterations, burning tokens on increasingly speculative changes.

Good prompt:

Implement user authentication for the Express app.

Phase 1: Add bcrypt password hashing to the User model.
Phase 2: Create /login and /register endpoints.
Phase 3: Add JWT middleware for protected routes.

After each phase, run `npm test` and fix any failures.
When all tests pass for all 3 phases, output <promise>done</promise>.

TDD workflows are the ideal use case. The loop runs tests, Claude reads failures, fixes code, and re-runs. The cycle continues until the test suite goes green. The test suite is the completion criterion.

Cost awareness matters. Each iteration consumes tokens -- a 50-iteration loop on a complex codebase can cost $50-100+ in API usage. The --max-iterations flag isn't just a safety net; it's a budget control. Start with 10-20 iterations for well-scoped tasks and increase only when needed.

Conclusion

The Ralph Wiggum loop reframes the role of the operator. Instead of writing code, you write the loop conditions. Instead of debugging, you write the tests that the loop debugs against. The model becomes the executor; the prompt becomes the program.

Huntley's framing goes further: software development as brick-by-brick Jenga is over. The loop is the new unit of work. The unresolved context window debate -- fresh processes vs continuous sessions -- reflects a deeper question in AI agent design: should agents accumulate state or start clean? The answer likely depends on the task. But the pattern itself, whether implemented as a bash one-liner or a plugin with exit code flow control, has become a fixture in how developers use Claude Code.

References

• Geoffrey Huntley, Ralph Wiggum as a "software engineer" (Jul 2025)
• Geoffrey Huntley, everything is a ralph loop (Jan 2026)
• Geoffrey Huntley, i ran Claude in a loop for three months, and it created a genz programming language called cursed (Sep 2025)
• CURSED language website and source code
• Ralph Wiggum plugin source

while :; do cat PROMPT.md | claude-code ; done

/plugin marketplace add anthropics/claude-code

/plugin install ralph-wiggum@claude-code-plugins

/ralph-loop Build a REST API with CRUD endpoints for a user model.
Run the test suite after each change. --max-iterations 20

.claude-plugin/
├── commands/
│   ├── ralph-loop.md       # /ralph-loop 斜杠命令
│   ├── cancel-ralph.md     # /cancel-ralph 停止循环
│   └── help.md             # /help 使用说明
├── hooks/
│   └── stop-hook.sh        # 拦截会话退出
└── scripts/
    └── setup-ralph-loop.sh # 创建状态文件

---
iteration: 3
max_iterations: 50
prompt: "Build a REST API with CRUD endpoints..."
promise: null
---

Make the app better. Fix any bugs you find
and add features that seem useful.

Implement user authentication for the Express app.

Phase 1: Add bcrypt password hashing to the User model.
Phase 2: Create /login and /register endpoints.
Phase 3: Add JWT middleware for protected routes.

After each phase, run `npm test` and fix any failures.
When all tests pass for all 3 phases, output <promise>done</promise>.