Updated November 2026
Where the Ralph Loop came from, how Anthropic’s Claude Code plugin runs it, how other tools copied the idea, and what happened when we tested it in Claude Code and in four chatbots.
The short version: The Ralph Loop is a way to keep an AI coding agent working on the same task until a check says it is finished, instead of letting it stop when it thinks it is done. Developer Geoffrey Huntley described it in July 2025 as a one-line loop that feeds the same instructions to the AI again and again. Anthropic now ships it as the Ralph Loop plugin for Claude Code, and the idea has spread to other coding agents, including OpenAI’s Codex, Google’s Gemini CLI and Block’s Goose. It works best when “done” can be checked by a test or a script. In our tests, the check mattered more than the loop: AI tools met clear rules on the first try, but their reports on their own work were sometimes wrong.
AI agents tend to stop when they believe a job is done, and that belief can be wrong. The Ralph Loop is a blunt fix: when the agent tries to stop, give it the same task again and let it look at what it already made. It keeps going until a finish line you set ahead of time is met, or until it hits a limit. If you are new to agents, our explainer on what an AI agent is covers the basics first, and what artificial intelligence is goes one step further back.
What is the Ralph Loop?
On July 14, 2025, developer Geoffrey Huntley published a post called “Ralph Wiggum as a ‘software engineer’” (Huntley). His whole technique fit on one line of code: a loop that reads a file of instructions, hands it to an AI coding agent, waits for it to finish, and then does the same thing again, forever. The instructions never change. What changes is the project folder, because each run leaves its work behind for the next one to read.
The name comes from Ralph Wiggum, the cheerful, oblivious boy in The Simpsons (Grokipedia). The joke is that the loop isn’t clever; it simply keeps trying. Huntley later said he ran Claude in a loop for three months to build a whole programming language called cursed, which uses Gen Z slang in place of normal programming commands (Huntley), and in January 2026 he followed up with a post titled “everything is a ralph loop” (Huntley).
How does Anthropic’s Ralph Loop plugin work?
Claude Code is Anthropic’s coding agent, and a plugin is an add-on you install into it. Anthropic added a “ralph-wiggum” plugin to Claude Code in November 2025 and renamed it Ralph Loop in January 2026. It now lives in Anthropic’s official plugin directory (GitHub), and its Claude Marketplace page showed 196,527 installs when we checked on November 8, 2026 (Claude).

The plugin uses a Stop hook, a small script Claude Code runs every time Claude finishes a reply (Claude Code docs). Once you start a loop:
- You type
/ralph-loopfollowed by your task, a finish phrase and a limit. - Claude works on the task and tries to stop.
- The Stop hook checks whether Claude’s last message contains the finish phrase, wrapped in
<promise>tags. If it doesn’t, the hook blocks the stop and sends the same task back. - Claude starts another round in the same session. It can see the files it changed and its earlier work.
- The loop is meant to end when Claude writes the finish phrase, when it reaches your limit, or when you type
/cancel-ralph.
Here is the shape of the command we used in our test. Copy it and change the task to your own:
/ralph-loop "Create glossary.md with exactly 150 AI terms for beginners. When you think you are finished, run: python3 check.py. Only output <promise>DONE</promise> when check.py prints ALL CHECKS PASSED." --completion-promise DONE --max-iterations 5
Two details trip up beginners. First, there is no limit unless you set one: the plugin’s default is unlimited, and its own README says to always use --max-iterations as a safety net (GitHub). Second, the finish phrase is a promise Claude makes about its own work. The plugin tells Claude not to write it unless it is true, but nothing checks it for you. That is why the strongest Ralph prompts include a real test, like a script that has to pass, before Claude is allowed to say “done.”
Two kinds of Ralph loop, plus a newer shortcut
People use “Ralph loop” for two different setups, and the difference matters. The third column, /goal, is a newer built-in command explained below the table.
| Fresh start each round | Same session (Anthropic plugin) | /goal (built in) | |
|---|---|---|---|
| How it repeats | A script starts a brand-new AI conversation every round | A Stop hook sends the same task back into the open session | After each turn, your goal is checked (in Claude Code, by a separate model) |
| What carries over | Only files and notes, plus the project’s saved change history | The whole conversation plus files | The whole conversation plus files |
| Who decides it’s done | Your script, or the round limit | Claude writes the finish phrase | A check against your goal; Claude Code uses a second model for it |
| Examples | Huntley’s original, snarktank/ralph, Goose, Gemini CLI | Ralph Loop plugin | Claude Code, Codex |
Starting fresh each round keeps the AI from getting bogged down in a long, messy conversation, which is why Huntley’s version and Ryan Carson’s popular snarktank/ralph work that way. Snarktank keeps a task list in a file called prd.json, writes what it learned to progress.txt, and stops after 10 rounds by default (GitHub). We explain why those files matter in our guides to progress files and feature lists for AI agents.
The newest option is /goal. In Claude Code you type a condition, such as “all tests pass and the code has no style errors,” and after every turn a separate model checks whether it holds. Anthropic’s docs say this means completion is “decided by a fresh model rather than the one doing the work” (Claude Code docs). OpenAI’s Codex has its own /goal in version 0.128.0 and later, where Codex weighs the evidence of its own progress (OpenAI).
What happened when we ran the plugin?
We gave Claude Code (running the Haiku 5.5 model) a task with a strict, checkable finish line: write a glossary of exactly 150 AI terms in alphabetical order, each with a 15 to 30 word definition that doesn’t repeat the term, an “Example:” line and a “See also:” line naming another term in the list. We also wrote a small checker script that prints ALL CHECKS PASSED only when every rule holds. We ran the 150-term task twice: once as a normal single run, and once inside the Ralph Loop plugin with a limit of five rounds. A shorter 40-term run first served as a warm-up.
| Run (November 8, 2026) | Checker at the end | Rounds | Time | Cost |
|---|---|---|---|---|
| 40 terms, single run | Passed | 1 | 1 min 4 s | US$0.02 |
| 150 terms, single run | Passed | 1 | 4 min 7 s | US$0.15 |
| 150 terms, Ralph Loop plugin | Passed | 2 | 4 min 0 s | US$0.14 |

Both versions finished the job. In round one of the loop, Claude ran the checker, which caught a list of 149 entries instead of 150 and a “See also” line that pointed to a term that wasn’t in the glossary. Claude fixed both, the checker passed, and Claude wrote the finish phrase. Even so, the plugin ran one more round, and we couldn’t tell from the log why. Round two re-ran the checker, found nothing to fix, and stopped, at almost no extra cost.
The single run did just as well, because our instructions told it to run the checker before saying it was done. On a job this size, the checker mattered most. A loop helps more with work too big for one sitting, such as Huntley’s three-month language project, or an overnight run through a long task list.
What this means for youWrite the finish line as something a script or a test can check, give the loop a round limit, and don’t pay for a loop on small jobs that a single run plus a checker already handles.
Do chatbots need a loop? Our no-code test
Most beginners won’t install Claude Code, so we tried the manual version in four chatbots, each in a private or temporary chat with default settings. We typed the same request into each: write an email to a landlord about a broken heater, in 90 words or fewer, saying it stopped working on November 3, with exactly three bullet points of fixes already tried, asking for a repair within 48 hours, ending with “Thanks, Sam [phone]”, and never using the word “urgent”.
All four met all six rules on the first try. Then we asked each one to check its own email against the rules and count the words one by one. Three of the four self-checks had problems:
| Assistant | First draft | Real word count | What its self-check said |
|---|---|---|---|
| ChatGPT | All 6 rules met | 72 | Numbered 72 words, then gave the total as 71. Still a correct pass. |
| Claude | All 6 rules met | 62 | 62 words, pass. Correct. |
| Gemini | All 6 rules met | 29 | Stalled twice when we reran the test, so no self-check. |
| Grok | All 6 rules met | 31 | Counted 31 words correctly, then marked the 90-word rule FAIL. |



Our email drafts from the first round, for comparison:



Meta AI asked for a birthday and agreement to its terms before it would answer, so we left it out. As in the plugin test, clear rules produced good first drafts, but the AI’s report on its own work was unreliable. Check against your list yourself, or with a tool such as your word processor’s word count.
How to use the Ralph idea without code
You don’t need Claude Code to borrow the useful part. In any chatbot:
- Write the finish line first. List what “done” means in items you can check: a word limit, required sections, a date that has to appear, a phrase that must not appear.
- Check the result yourself. Go down your list. Use a word counter for word counts instead of asking the AI.
- Send back only the gaps. Name what failed and ask it to keep what already works, rather than just saying “try again.” The prompt below does that.
- Stop after two or three rounds. If it still isn’t right, the instructions usually need rewriting, not another round.
Check your draft against my list. These items are not met yet: [paste the ones that failed]. Keep everything that already works and continue from your current draft. Change only what is needed to meet those items.
This is the same habit our CLEAR prompting guide calls refining, and the AI feedback loop guide shows how to save what you learn from each round so the next task starts better.
What does a loop cost, and what can go wrong?
A loop keeps spending until it stops. Huntley shared a message from an engineer he taught who said they delivered a $50,000 contract for $297 using Ralph with the Amp coding agent (Huntley); that is a self-reported figure, not an audited one. A community post on Alibaba Cloud’s blog estimates 5 to 10 rounds for small tasks, 20 to 30 for medium ones and 30 to 50 for large ones (Alibaba Cloud). Long unattended runs can surprise you: when a hobbyist let OpenAI’s GPT-6 Astra play the puzzle game Portal on its own for close to 24 hours, the bill came to $571, as we covered in our daily newsletter.
- Always set a limit.
--max-iterationsin the plugin, a round count in your own script. - Work on a copy. Keep a backup, or use version control (a tool such as Git that saves every change), so you can undo anything the agent does.
- Check the finish line, not the promise. A test or script that has to pass is stronger than the agent’s word.
- Watch the first rounds. If the agent is going in circles, cancel and rewrite the task.
Where else does the Ralph idea show up?
- snarktank/ralph, by Ryan Carson: a fresh-start loop for the Amp coding agent or Claude Code, driven by a task list (GitHub).
- Vercel Labs ralph-loop-agent: an experimental add-on that adds a check-and-retry loop to Vercel’s AI toolkit, for developers building their own agents (GitHub).
- Goose, the open-source agent from Block: its Ralph Loop tutorial starts each round fresh and has a second model review the first model’s work (Goose docs).
- Gemini CLI: an official Ralph extension that clears the conversation between rounds (GitHub).
- Codex and Claude Code: both now have
/goal, a built-in way to keep working until a condition is met (OpenAI, Claude Code docs).
How is it different from Karpathy’s autoresearch?
Andrej Karpathy’s autoresearch, released in March 2026, also runs an AI agent in a loop, but with a different aim: it tries changes to a small model’s training setup and keeps the ones that improve results (GitHub). The Ralph Loop works toward a fixed finish line, while autoresearch keeps looking for improvements. Our autoresearch explainer covers it in detail, and AI agent orchestration shows how loops fit into multi-agent setups.
Frequently asked questions
Do I need the plugin to use a Ralph loop in Claude Code?
No. The plugin is the easiest way, but you can write your own Stop hook, run Huntley’s original one-line loop script, or use the built-in /goal command (Claude Code docs).
Is the Ralph Loop the same as asking the AI to check its own work?
Not quite. The loop controls when to keep going, but its finish line is only as good as the check behind it. In our test, two of the three chatbots that checked their own emails got their own grading wrong, so pair the loop with a script, a test or your own checklist.
How many rounds does a Ralph loop take?
It depends on the job. Our glossary test took two rounds, and the second only confirmed the first. A community post on Alibaba Cloud’s blog estimates 5 to 10 rounds for small tasks and 30 to 50 for large ones (Alibaba Cloud). Set a limit either way.
Can I use the Ralph idea for writing or research?
Yes, as long as “done” can be checked: a word limit, required sections, a number of sources, questions that must be answered. For taste and tone, a loop can’t judge, so you still read it yourself.
Why is it called the Ralph Loop?
Geoffrey Huntley named it after Ralph Wiggum from The Simpsons, a character known for cheerful persistence rather than brilliance (Huntley). Anthropic’s plugin was first called ralph-wiggum and was renamed Ralph Loop in January 2026.
Made for regular people, by a real person
One plain-English AI tip or tool a day, tested before we recommend it. Curated and edited by a human.
Free forever. Unsubscribe anytime.
You may also like
- What Are AI Agents?
- What Is a Progress File?
- Feature Lists for AI Agents
- Build a Feedback Loop AI Skill
- Karpathy’s AutoResearch Explained
- AI Feedback Loop Guide
- Vibe Coding Explained
- How to Use Claude AI
- How to Use AI
- AI Tools Directory
- Best AI Tools for Beginners
Sources
- Geoffrey Huntley: Ralph Wiggum as a “software engineer” (July 14, 2025)
- Geoffrey Huntley: cursed (September 9, 2025)
- Geoffrey Huntley: everything is a ralph loop (January 17, 2026)
- Anthropic: Ralph Loop plugin source and README
- Claude Marketplace: Ralph Loop
- Claude Code docs: Hooks
- Claude Code docs: Keep Claude working toward a goal
- OpenAI: Using goals in Codex
- snarktank/ralph
- Vercel Labs: ralph-loop-agent
- Goose docs: Ralph Loop tutorial
- Gemini CLI extensions: ralph
- Alibaba Cloud: From ReAct to Ralph Loop (January 15, 2026)
- karpathy/autoresearch
- Grokipedia: Ralph Wiggum
- Our tests: Claude Code with the Ralph Loop plugin, and ChatGPT, Claude, Gemini and Grok in private chats, November 8, 2026. Screenshots by Beginners in AI.

