PlugWiki

Ralph Wiggum (ralph-loop) Plugin for Claude Code: Install, Use and Stop

Anthropic's free Claude Code plugin that re-sends the same prompt after every turn until a done-phrase or an iteration cap.

Hooks
1
included
Commands
3
included
Stars
45.7K
on GitHub

ralph-loop makes Claude Code keep working on the same prompt, turn after turn, until it prints a done-phrase you chose or reaches an iteration cap. This is the Ralph Wiggum technique, Geoffrey Huntley's idea of running a coding agent in a loop. Each pass starts from the files and git history the last pass left. Know before you start: with no cap and no done-phrase the loop never stops on its own, so always set a cap.

Good for

  • Developers with a clear task and tests that say when it is done
  • People starting a new project who want Claude to keep building overnight
  • Anyone fixing failing tests where another try usually helps
  • People who can write exact done-criteria into a prompt

Install ralph-loop

Claude Code

  1. 1

    Copy this prompt.

    Install the ralph-loop plugin in Claude Code. Run this command:

/plugin install ralph-loop@claude-plugins-official

Then check that it loaded and tell me how to use it.
  2. 2

    Paste it into Claude Code. It shows the change and asks before running it.

Requires Claude Code, bash, jq and perl.

Use the first line. Claude Code adds the official marketplace the first time you start an interactive terminal session, so the second option is only for when it is missing. Pick user, project or local scope when asked. The hook needs bash, jq and perl; on Windows use Git for Windows. Always set --max-iterations when you start a loop. Old ralph-wiggum installs: run the shell line if the /ralph-loop: commands are missing.

From the vendor's docs. Source.

Key facts

Publisher
Anthropic
License
Apache 2.0, free
Version
1.0.1
Last commit
2026-10-26 to the plugin folder
Installs
196,527 on claude.com as of 2026-11-02
Contents
3 commands, 1 hook. No skills, agents or MCP servers.
Requires
Claude Code; bash, jq and perl for the hook (Git for Windows on Windows)
Works in
Claude Code terminal, desktop app Code tab, VS Code extension. Not cloud sessions or claude.ai chat.
Official listing
Claude Marketplace, marked Anthropic verified
Marketplace
claude-plugins-official, category development
Technique by
Geoffrey Huntley, first described 2025-07-14
Formerly named
ralph-wiggum, renamed 2026-01-06

What it includes

  • Starts a loop that re-sends your prompt each time Claude tries to finish

    Takes your prompt, an optional iteration cap and an optional done-phrase, and saves them in a state file in your project. Shown as /ralph-loop:ralph-loop.

    Try: “/ralph-loop "Build a REST API for todos. Requirements: CRUD operations, input validation, tests. Output <promise>COMPLETE</promise> when done." --completion-promise "COMPLETE" --max-iterations 50”

    Runs code · /ralph-loop

  • Stops the active loop by deleting its state file

    Deletes the loop's state file and tells you which iteration it was on. Says so if no loop is running. Shown as /ralph-loop:cancel-ralph.

    Try: “/cancel-ralph”

    Delete · /cancel-ralph

  • Explains the Ralph technique, the commands and done-phrases

    Prints a short guide to the plugin. Shown as /ralph-loop:help. It names the state file with a leading dot, which does not match the real file.

    Try: “/ralph-loop:help”

    /help

  • After each turn, stops Claude from ending and re-sends your prompt while a loop is active

    Runs every time Claude finishes a turn. If a loop is active it checks the cap and the last reply for your done-phrase. If neither ends the loop, it adds one to the counter and sends the same prompt again.

    Delete · Stop hook

From the official docs

Permissions

Medium risk

A loop with no limit keeps running and spending your usage until you stop it, and Claude still edits files and runs commands on every pass. Always set an iteration cap, and keep permission prompts on unless you run it in a sandbox.

What it can do

  • Read your data
  • Create and change things
  • Delete things
  • Read-only mode

Watch out for

  • Runs forever unless you set a limit

    The iteration cap defaults to unlimited, and the setup script warns the loop cannot be stopped manually without a cap or a done-phrase. Write the cap with a space (--max-iterations 20), not an equals sign or a leading zero, which are reported to remove it. github.com

  • Cost grows with every iteration

    Each pass is a full Claude turn on your plan or API key. One user reported 6,239 iterations over about 11.7 hours before anyone noticed, so set a cap and watch the first few passes. github.com

  • Claude keeps its normal power on every pass

    The loop adds turns, not permissions. Whatever your session lets Claude edit or run, it can do on each pass, so run unattended loops in a sandbox or a project you can restore from git. github.com

  • One loop can block other sessions in the same project

    The state file is per project. If the session ID is empty when the loop starts, the hook blocks stops in every session in that folder (open issue). Run /cancel-ralph or delete .claude/ralph-loop.local.md to end it. github.com

  • Backticks in your prompt can break the start command

    Your prompt goes through a shell command, and users report that backticks trip Claude Code's command check. Avoid backticks in the prompt or put the details in a file. github.com

  • How to stop a running loop

    Run /cancel-ralph, which deletes the state file. Pressing Esc interrupts the turn and the Stop hook does not run after an interrupt, but the state file stays until you cancel. code.claude.com

  • A bash hook runs after every turn

    Once installed, stop-hook.sh runs each time Claude finishes a turn. It exits at once when no .claude/ralph-loop.local.md exists, and it needs bash, jq and perl. github.com

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details
Turning on read-onlyNo read-only mode. The loop gives Claude repeated turns with whatever permissions your session already has. The hook itself only reads the transcript and edits or deletes its own state file.
Data retentionThe plugin sends nothing off your machine. Loop state is one file in your project's .claude folder, deleted when the loop ends.

Works in

Works in the Claude Code terminal, the desktop app's Code tab and the VS Code extension. It does not run in claude.ai chat or cloud sessions.

Tap an app to see how to set it up and any known problems.

Examples

  • Build a small REST API with tests until every requirement is met

    /ralph-loop "Build a REST API for todos. Requirements: CRUD operations, input validation, tests. Output <promise>COMPLETE</promise> when done." --completion-promise "COMPLETE" --max-iterations 50

    Ends when Claude prints COMPLETE, or after 50 passes if it never does.

    Source

  • Fix an auth bug until the tests pass

    /ralph-loop "Fix the token refresh logic in auth.ts. Output <promise>FIXED</promise> when all tests pass." --completion-promise "FIXED" --max-iterations 10

    Ends when Claude prints FIXED, or after 10 passes.

    Source

  • Refactor with a hard cap and no done-phrase

    /ralph-loop "Refactor the cache layer" --max-iterations 20

    Runs exactly 20 passes, then stops.

    Source

  • Add tests until a done-phrase is true (no cap, so avoid unattended)

    /ralph-loop "Add tests" --completion-promise "TESTS COMPLETE"

    Only the phrase ends it. Add a cap in case Claude never prints it.

    Source

What people say

People like how little it takes to let a clear task run to the end and dislike the open bugs and the cost of loops that do not stop.

What people like

  • Replaces writing your own bash loop, and the README has ready prompt examples.
  • Good at letting long, well-defined tasks run to the end.
  • Free, official and one command to install.

Common complaints

  • Huntley, who coined the technique, says Claude Code's version is not the real thing.
  • Far from the hype: you still define the result and maintain it.
  • Runaway loops burn usage, and many Stop-hook bugs are still open.

In their words

BlogJul 2025
“Ralph is a technique. In its purest form, Ralph is a Bash loop.”
Geoffrey HuntleyBlogJul 2025
“As a final closing remark, I'll say, "There's no way in heck would I use Ralph in an existing code base" though, if you try, I'd be interested in hearing what your outcomes are.”
Geoffrey HuntleyHacker NewsJan 2026
“ralphs is good at letting things complete, but is far from "making commercial software for $10"”
8noteGitHub issueMay 2026
“A /ralph-loop started in one Claude Code session ran 6,239 iterations over ~11.7 hours before being noticed”
stevencarpenter
3 more quotes
GitHub issueJan 2026
“The ralph-wiggum plugin's /ralph-loop command silently ignores --max-iterations when using the equals-sign syntax (--max-iterations=5), causing infinite loops instead of stopping after N iterations.”
genesisczGitHub issueJul 2026
“the Stop hook did not detect it and fed the same prompt back for another iteration. This happened twice in a row across two separate turns”
IamJPGomezGitHub issueAug 2026
“Three separate sessions in one working day, 14–21 minutes of churn each. The user sees the agent repeat an identical completion message dozens of times before the harness intervenes.”
Kevin-Kurka

Questions

What is the Ralph Wiggum technique?

Geoffrey Huntley's name for running a coding agent in a loop on the same prompt. His post says "In its purest form, Ralph is a Bash loop." Each pass picks up from the files and git history the last pass left. This plugin runs the loop inside one Claude Code session instead.

How do I install ralph-loop?

Use the install box at the top of this page. Claude Code adds the official marketplace on first start, so the first command is usually enough. It asks you to pick a scope: user, project or local.

How do I stop a Ralph loop?

Run /cancel-ralph (shown as /ralph-loop:cancel-ralph). It deletes the state file and tells you which iteration it was on. The loop also ends when Claude prints your done-phrase or reaches the cap. Pressing Esc interrupts the current turn but does not remove the loop.

Is ralph-loop free, and what does it cost to run?

The plugin is free under Apache 2.0. Each iteration is a normal Claude turn, so it uses your plan usage or API tokens, and long loops add up. The README quotes Huntley's own claim of a $50k contract finished for $297 in API costs. Treat that as his anecdote, not a test.

Why does my loop not stop when Claude prints the promise?

The done-phrase must match exactly, inside <promise>YOUR PHRASE</promise> tags in Claude's last message. Open issues also report a correctly written phrase being missed, and a loop ending after one turn because the hook reads the chat log too early. Run /cancel-ralph and always set a cap as a backstop.

Was ralph-loop renamed from ralph-wiggum?

Yes. Anthropic renamed it on 2026-01-06, citing legal guidance. The commands now start with /ralph-loop:. If they are missing after an old install, reinstall from the official marketplace.

Does ralph-loop work on Windows?

Yes, with Git for Windows. The hook is a bash script, and it fails if bash resolves to WSL. The README has a workaround that points the hook at Git's bash.exe.

Does it work in claude.ai or Claude Code on the web?

No. Chat on claude.ai does not run it, and cloud sessions do not load plugins you installed on your own machine. It runs in the Claude Code terminal, the desktop app's Code tab and the VS Code extension.

ralph-loop vs a plain bash while loop?

A bash loop starts a fresh process on every pass. The plugin stays in one Claude Code session and needs no script from you. Huntley published a video titled "why Claude Code's implementation isn't it", so pick the bash loop if you want the original behavior.

ralph-loop vs the built-in /goal command?

Both keep Claude working after each turn. ralph-loop re-sends the same prompt until an exact done-phrase or a cap. /goal is built in, and a separate model checks your condition after every turn.

Information

updated Nov 2, 2026

Runs in
Claude Code
Repository
anthropics/claude-plugins-official

anthropics/claude-plugins-official

Sources

Docs, issue trackers and discussions this page is built from.

Show all 32
  1. Anthropic marketplaces · code.claude.com
  2. Discover and install plugins · code.claude.com
  3. ralph-loop README · github.com
  4. Ralph Wiggum as a "software engineer" · ghuntley.com
  5. setup-ralph-loop.sh · github.com
  6. plugin.json · github.com
  7. LICENSE · github.com
  8. Commits to ralph-loop · github.com
  9. ralph-loop on Claude Marketplace · claude.com
  10. ralph-loop plugin folder · github.com
  11. stop-hook.sh · github.com
  12. marketplace.json · github.com
  13. Rename ralph-wiggum to ralph-loop (PR 142) · github.com
  14. ralph-loop command · github.com
  15. cancel-ralph command · github.com
  16. help command · github.com
  17. bug(ralph-loop): stop hook fires in all sessions when CLAUDE_CODE_SESSION_ID is unset · github.com
  18. Hooks reference · code.claude.com
  19. Backticks in /ralph-loop prompt · github.com
  20. ralph-loop does not respect --max-iterations=X · github.com
  21. --max-iterations with a leading zero · github.com
  22. Ralph Wiggum (and why Claude Code's implementation isn't it) · youtube.com
  23. /goal · code.claude.com
  24. Fails to detect <promise> tag · github.com
  25. Loop ends after one turn: transcript race · github.com
  26. Stop hooks ignore stop_hook_active · github.com
  27. Stop hook fires in all sessions · github.com
  28. Start command permission check error · github.com
  29. Bypass-permissions mode switched off each turn · github.com
  30. 'Ralph Wiggum' loop prompts Claude to vibe-clone commercial software for $10 HR · news.ycombinator.com
  31. Hacker News discussion · news.ycombinator.com
  32. Stop-hook bug report · github.com

Updated Nov 2, 2026.