Ralph Loop: How to Put AI in a Loop and Go to Sleep

Some time ago, I stumbled upon something that changed my thinking about how you can work with Claude Code. It's called Ralph Loop, a plugin that does one simple thing: it lets AI work on a task in a loop, iteratively, until it succeeds. Or until it hits an iteration limit, so you don't burn through your subscription or tokens.

Where the idea came from

Ralph Loop is an implementation of the so-called Ralph Wiggum technique, named after the character from The Simpsons. It was popularized by Geoffrey Huntley and boils down to an absurdly simple idea:

while true; do
  cat PROMPT.md | claude
done

In other words: give AI a prompt, let it try. If it fails, let it try again. And again. And again.

At first glance, it looks primitive. But it works, because language models are genuinely good at iteratively fixing their own mistakes, as long as they can see what they did before and receive some kind of feedback. Huntley put it this way: it's better to fail predictably than to succeed unpredictably.

How it works technically

The plugin implements this mechanism inside Claude Code using a stop hook. It's a function that intercepts the moment when Claude wants to end the session. Instead of letting it exit, the hook blocks the exit and re-injects the same prompt. The workflow looks like this:

1. You launch a command with a prompt.
2. Claude works on the task.
3. Claude tries to end the session.
4. The stop hook intercepts the exit and checks whether a predefined completion signal appeared in the response.
5. If not, the same prompt is fed again.
6. Claude sees its previous changes in the repo and fixes errors.
7. It repeats until it meets the completion condition or exhausts the iteration limit.

The key point is that the code stays in the repository between iterations. Git history acts as the model's memory. Claude sees what it did in the previous attempt and can learn from it. The loop runs inside the current Claude Code session, you don't need an external bash loop.

Installation and setup

The ralph-wiggum plugin is available in the official Claude Code plugin marketplace. Installation is two commands typed directly in the Claude Code terminal:

/plugin marketplace add anthropics/claude-code
/plugin install ralph-wiggum@claude-plugins-official

The first one adds Anthropic's official plugin repository. The second installs the plugin itself. After installation, two new commands become available: /ralph-loop to start a loop and /cancel-ralph to stop it.

How to use Ralph Loop

The basic command consists of three elements: a task description, an iteration limit, and a completion phrase:

/ralph-loop "Your task" \
  --max-iterations 20 \
  --completion-promise "DONE"

The --completion-promise parameter is a phrase that Claude must output for the loop to consider the task complete. Important note: this uses exact string matching, so you can't define multiple completion phrases. That's why --max-iterations is really your main safeguard, and you should always set it, because you can never be sure whether the AI will correctly interpret your instructions.

A good prompt should include clear success criteria and explicitly tell the model what to do when it gets stuck. For example:

/ralph-loop "Implement REST API for todos.

Requirements:
- CRUD endpoints working
- Input validation in place
- Tests passing with >80% coverage
- README with API docs

After 15 iterations, if not complete:
- Document what's blocking progress
- List what was attempted
- Suggest alternative approaches

Output DONE when complete." \
  --max-iterations 20 \
  --completion-promise "DONE"

You can stop the loop at any moment with /cancel-ralph or a simple Ctrl+C.

When it makes sense

The best scenarios are those with automated validation. Tests, linting, builds, CI, anything that gives the model unambiguous feedback: it works or it doesn't.

A good example is a typical TDD (Test-Driven Development) workflow, where AI writes code, tests fail, AI fixes the code, until all tests pass. Another great use case is refactoring and framework migrations. You can clearly define success criteria, and the AI can verify them on its own.

The philosophy is this: instead of hand-holding the AI step by step, you define success conditions upfront and let the agent iterate toward them. Failures become data. Each iteration improves the approach based on what broke.

When it doesn't work

This isn't a magic solution. There are situations where Ralph Loop simply doesn't deliver. When the task requires creative architectural decisions rather than mechanical iteration, or the specification is vague and the AI has no way to validate whether it's doing the right thing, that's a recipe for failure. Without clear, automated feedback, the model will spin in circles without making progress or implement something that merely pretends to be the expected outcome.

The rule is simple: if you can't describe the success condition in a way that can be verified automatically, Ralph Loop won't work well.

My experience: Ralph Loop and the BMad method

Theory is theory, but I want to tell you how I actually used Ralph Loop on a real project. And why I believe it's not the plugin that matters most, but what you feed into it.

I use the BMad method (Build More Architect Dreams), which I've written about separately. In short: it's a structured process for running a project with AI, where before anyone starts coding, you go through phases of analysis, brainstorming, and planning, and only then implementation. Each phase produces documentation in the repository: product brief, PRD, UX design, architecture, epics and stories with acceptance criteria, and finally an additional implementation readiness validation.

When I had gone through all the BMad stages and had a truly detailed implementation plan, with all required documents, epics broken down into stories, acceptance criteria for every element, and a designed architecture, that's when I fired up Ralph Loop.

I left the computer running overnight. Ralph Loop picked up stories from the plan one by one, implemented them, ran code review, fixed errors, moved on. Through all the epics, through all the stories, through the entire sprint cycle I had designed in BMad.

I woke up in the morning and the application was ready. Throughout the night, agents built everything on their own, iterated, fixed issues. And the application worked! Not "kind of," not "good enough," not "fine for a demo." It was genuinely high-quality code.

This experience convinced me of one thing: Ralph Loop is only as good as the plan you give it. Without BMad, without detailed documentation, without thoughtful architecture and clear criteria, the same plugin would just spin in circles and burn tokens. With a good plan, it can truly deliver the overnight coding that so many dream about.

Practical tips

From what I've gathered from the community, blogs, and my own experience, a few things keep coming up.

The prompt is everything. This is not a tool that thinks for you. The community repeats this like a mantra: success depends on writing good prompts, not on the model itself. It's better to write solid documentation and a good prompt and use a cheaper, faster model than to try building an entire application with a single prompt on even the smartest model. The more precise your requirements, checklist, and completion conditions, the better.

Always set max-iterations. Without it, you can create an infinite loop. Completion promise relies on exact string matching and isn't foolproof, so the iteration limit is your ultimate safeguard.

Break tasks into phases. Instead of a single prompt like "build a SaaS app," it's better to split it into stages and run a separate loop for each phase:

/ralph-loop "Phase 1: User authentication (JWT, tests).
Output PHASE1_DONE when complete." \
  --max-iterations 20 \
  --completion-promise "PHASE1_DONE"

Always work in a git directory. If something goes wrong, you can revert changes. Each iteration leaves a trace in the commit history.

Start without guardrails. This is advice straight from the plugin docs: let Ralph try first, then add constraints where it fails. Every failure teaches you what guardrails to add to the prompt.

Room for improvement

There's one important issue that critics raise. The plugin runs within a single session, which means the context window grows with each iteration. After a dozen or so passes, the model may start performing worse because the context is too large. This phenomenon is known as context rot.

The original Ralph technique (the simple bash loop) works differently: each iteration is a new session with a clean context, and state is preserved in files and git history. This way, the model always operates within an optimal context window range. The plugin is more convenient to use, but this difference can matter for longer tasks.

There are also alternative implementations, such as ralph-claude-code, which start each iteration as a fresh instance with a clean context and maintain memory between iterations through progress.txt files and git history. It's worth keeping this in mind, especially for tasks requiring many dozens of iterations.

Final thoughts

The idea of "give it a spec and come back in the morning" is tempting. And from what people describe in the community, and from my own experience, it really works. Provided that the task is well-defined and has automated validation. Even better if you first go through a proper planning process, such as BMad, which gives the agent full context of what to build and how.

If you want to learn more about BMad and find out what prompts I use when combining BMad with Ralph Loop, feel free to reach out, I'll tell you how I train development teams to leverage AI in their work.