Skip to content

// Engineering - October 26, 2026

The Ralph loop: run a coding agent off a task board.

The Ralph loop, or Ralph Wiggum loop, runs an AI coding agent again and again with the same prompt. In Geoffrey Huntley's original version, from July 2025, each pass is a new agent session that picks one task from a plan, does it, checks it and exits. Then a shell loop starts the next pass.

What is the Ralph loop?

The Ralph loop is a way of running a coding agent unattended: the same prompt goes to the agent again and again, and each pass does one task. Geoffrey Huntley described it in his post Ralph Wiggum as a "software engineer" (July 14, 2025, last updated February 19, 2026). He wrote: "Ralph is a technique. In its purest form, Ralph is a Bash loop." His example is one line:

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

PROMPT.md holds the instructions, and claude-code stands in for the agent's command. With Claude Code today, that command is claude -p, the non-interactive mode that runs one prompt and exits. Huntley sums up the design: "Ralph works autonomously in a single repository as a single process that performs one task per loop."

The name comes from Ralph Wiggum of The Simpsons. Thoughtworks put the technique on its Technology Radar on April 15, 2026, in the Assess ring, and describes it this way: "Each iteration starts with a fresh context window: the agent selects a task from a specification or plan, implements it, and the loop restarts with a fresh context."

How does a Ralph loop work?

Each pass reads the same files, does the most important open task, checks it and leaves notes for the next pass. The pieces in Huntley's post are:

  1. A fixed prompt. The prompt never changes between passes. When the agent does something wrong, you add a line to the prompt, which Huntley calls putting up a sign.
  2. Specs and a plan. Specifications live in specs/. The plan, fix_plan.md, is a to-do list sorted by priority. The agent reads both on every pass, and you "trust Ralph to decide what's the most important thing to implement".
  3. One task per pass. In Huntley's words, "you need to ask Ralph to do one thing per loop. Only one thing." The reason is context: "The more you use the context window, the worse the outcomes you'll get."
  4. Back pressure. Tests, type checks and builds reject bad work before it is kept. "Anything can be wired in as back pressure to reject invalid code generation."
  5. Notes for the next pass. Because the next pass starts with an empty context, the agent writes down what it learned, updates the plan and commits. Huntley asks for the same on tests, with comments "leaving little notes for future iterations by the LLM, explaining why a test exists and its importance".

Fresh context is the point of the design, and also its cost. Thoughtworks notes: "Using a fresh context window on each iteration avoids the quality degradation that comes from accumulated context, though at significant token cost." For more on why less context often works better, see our post on context engineering for AI agents.

Bash loop, ralph-loop plugin or /goal: which should you use?

Use a bash loop for a long list of separate tasks, and the plugin or /goal for one task you want Claude to keep working on. All three repeat the work. The difference is whether each pass gets a fresh session. As of October 2026, the three options work like this:

Option How the next pass starts Context between passes How it stops
Bash loop (Huntley) Your shell starts a new agent process Fresh every pass. State lives in files and git, or on a board as shown below. Whatever your script decides, or Ctrl+C
ralph-loop plugin (Anthropic) A Stop hook blocks the exit and feeds the same prompt back Same session. "The loop happens inside your current session." --max-iterations (default unlimited), a --completion-promise phrase, or /cancel-ralph
/goal (built into Claude Code) "After each turn, a model checks whether the condition holds" and starts another turn if not Same session The condition is met or judged impossible, an error you have to fix, or /goal clear

The plugin was first published as ralph-wiggum and renamed ralph-loop in Anthropic's official plugin marketplace in January 2026. You install it with /plugin install ralph-loop@claude-plugins-official, which opens the plugin's details so you can choose an install scope. Its README notes that the completion promise "uses exact string matching" and says: "Always use --max-iterations as a safety net to prevent infinite loops on impossible tasks".

Huntley prefers the fresh process. His post now links a video under the line "watch this to learn why the claude code plugin isn't it". Our take: if the work is a list of separate tasks, start a new process for each one. If it is one task that needs several tries, such as getting a test suite to pass, the plugin or /goal is simpler.

When should you not use a Ralph loop?

Don't use one where a wrong guess is expensive, or where nothing can check the work. Huntley is clear about the limits:

  • Existing code bases. "There's no way in heck would I use Ralph in an existing code base". He adds that it "works best as a technique for bootstrapping Greenfield, with the expectation you'll get 90% done with it."
  • Breakage. He warns that "you'll wake up to a broken codebase that doesn't compile from time to time," and then you decide whether to reset or write new prompts to rescue it.
  • No one to supervise. He also writes that "engineers are still needed". The loop runs without you, but someone still has to tune the prompt and judge the result.

The plugin's README lists the same limits. It says the loop is not good for "Tasks requiring human judgment or design decisions" or "Tasks with unclear success criteria". Cost is the other limit. Claude Code's --max-budget-usd flag stops a print-mode run once its estimated spend reaches a cap, and --max-turns limits the turns in a single run.

How do you run a Ralph loop off a Flux board?

Replace the plan file with a board column: each pass takes the top card in Ready, works it, comments and moves it to Needs review. The loop stays Huntley's, with a fresh process per pass. The plan and the notes move to a board, where people can see and reorder them without opening the repository:

Huntley's version On a Flux board
fix_plan.md, sorted by priority The Ready column. A person puts the most important card on top. get_board returns each column's cards in board order.
The agent chooses the next task The agent takes the first card. This is a change from Huntley's version: people choose the order.
Tests as back pressure A "Done when" list in the card description. get_card returns the description and comments, but not checklist items or labels.
Notes for the next pass A signed comment on the card, plus the git commit
Huntley watching the run The Needs review column. A person checks the work and moves the card to Done.

Set up a board with four columns: Ready, In Progress, Needs review and Done. Create an API key with the Write scope in Settings under API Keys, and export it as FLUX_API_KEY. Write each card so a fresh agent can finish it from the card alone: one goal, the files to touch, and a "Done when" list of checks. Our guide to acceptance criteria for AI agents shows how. Then save this as PROMPT.md:

You are one pass of a Ralph loop. Do one card, then stop.

1. Call get_board with board_id "YOUR_BOARD_SHORT_ID". Note the column
   ids of Ready, In Progress and Needs review.
2. If Ready has no cards, reply with the single word RALPH_EMPTY and stop.
3. Take the first card in Ready. Move it to In Progress with move_card.
   Read it with get_card, using the card's id (its UUID).
4. Do only what the card describes. Search the code before you add
   anything. Don't assume something is missing.
5. Run every check under "Done when" in the description. If one fails,
   fix it and run it again.
6. Commit your change. Put the card's humanId in the commit message.
7. Comment on the card with add_comment: what you changed, each check
   and its result, and anything you were unsure about. End the comment
   with "- ralph".
8. Move the card to Needs review. Never move a card to Done.
9. If you can't finish, comment what blocked you, sign it "- ralph",
   move the card to Needs review and stop.

And this as ralph.sh, next to it:

#!/usr/bin/env bash
# ralph.sh - one fresh Claude Code run per card, until Ready is empty
set -u
MAX_PASSES=20
: "${FLUX_API_KEY:?export FLUX_API_KEY first}"
command -v jq >/dev/null || { echo "ralph.sh needs jq" >&2; exit 1; }

# Write the Flux MCP config to a private temp file
umask 077
CFG=$(mktemp)
trap 'rm -f "$CFG"' EXIT
printf '{"mcpServers":{"flux":{"type":"http","url":"https://flux.umin.ai/api/mcp","headers":{"Authorization":"Bearer %s"}}}}' "$FLUX_API_KEY" > "$CFG"

for pass in $(seq 1 "$MAX_PASSES"); do
  echo "== pass $pass"
  result=$(claude -p "$(cat PROMPT.md)" \
    --mcp-config "$CFG" \
    --allowedTools "Read,Edit,Write,Bash(npm test *),Bash(git add *),Bash(git commit *),mcp__flux__*" \
    --disallowedTools "Read(/$CFG)" \
    --max-turns 60 \
    --output-format json | jq -r '.result')
  echo "$result" | tail -n 5
  if echo "$result" | grep -q "RALPH_EMPTY"; then
    echo "Ready is empty. Stopping."
    break
  fi
done

What each part does, with flags from the Claude Code CLI reference:

  • claude -p in a for loop starts a new session for every pass, so each card gets a fresh context.
  • MAX_PASSES and RALPH_EMPTY are the stopping rules. The loop ends after 20 passes, or as soon as the agent reports an empty Ready column. --output-format json returns the agent's final reply in the result field, which jq extracts.
  • --max-turns limits one pass, so a stuck card can't run forever. A pass that hits the limit exits with an error and can leave its card in In Progress, so check that column when the loop ends. Add --max-budget-usd if you want a spending cap per pass.
  • --allowedTools lists what runs without asking. From Claude Code v2.1.302, a claude -p run with no permission mode set starts in Manual mode, where a call that needs approval is denied unless something approves it. mcp__flux__* allows every tool from the server named flux. Add an entry for every command your "Done when" checks use, such as Bash(npm run *), or the agent can't run them. --disallowedTools "Read(/$CFG)" stops the agent from reading the temp file that holds your key (a // rule is an absolute path).

Treat this as a starting point. Run it on its own branch or worktree and watch the first few passes. When you see a mistake, add a line to PROMPT.md, as Huntley does.

What should you know about Flux before you loop?

The board keeps the queue and the notes, but the rules in PROMPT.md are instructions, not locks. Five things to know as of October 2026:

  • Run one loop per Ready column. Flux has no card locking or atomic claiming, so two loops reading the same column can take the same card. For more than one loop, give each its own column or board. Our post on coordinating multiple AI coding agents covers lanes and git worktrees.
  • Comments are the record. Changes made over MCP are not written to the activity log, so they can't be undone from it. Moves and comments made over MCP also don't push a live update to a board someone already has open, so reload it to see the latest.
  • Sign every comment. Anything the loop writes appears under the name of the person who created the API key, and get_card returns comments without author names. The "- ralph" signature tells people and later passes who wrote what.
  • A card moved back goes to the bottom. move_card places the card at the end of the target column. If you send a card back to Ready, move it to the top yourself if it should go next.
  • Nothing stops a move to Done. A key with the Write scope, whose owner is at least a member of the workspace, can move a card to any column on the board. "Never move a card to Done" works only because it is in the prompt.

Agents that connect over MCP or the REST API with a member's API key never take a seat on any plan. For the full board layout with a review column, see the kanban board for AI agents guide, and the Flux MCP server page for all 12 tools.

// FAQ
06 questions
01

Why is it called the Ralph Wiggum loop?

+

It is named after Ralph Wiggum, the character from The Simpsons. Geoffrey Huntley, who described the technique in July 2025, says the joke is the point: "the technique is deterministically bad in an undeterministic world." Each pass can go wrong, but the loop keeps going, and you improve the prompt each time you see a mistake.

02

Is the ralph-loop plugin for Claude Code the same as the Ralph loop?

+

It is the same idea with different mechanics. Huntley's version starts a new agent process for every pass, so each pass gets a fresh context. Anthropic's ralph-loop plugin uses a Stop hook to feed the same prompt back into your current session, so the session carries on between passes. Its README says: "The loop happens inside your current session."

03

How do you stop a Ralph loop?

+

A bash loop stops when you press Ctrl+C or when your script decides, for example after a set number of passes or when the agent prints an agreed word. The ralph-loop plugin stops at --max-iterations, when Claude outputs the --completion-promise text inside promise tags, or when you run /cancel-ralph. Its README says to always set --max-iterations as a safety net. The default is unlimited.

04

Does the Ralph loop only work with Claude Code?

+

No. Huntley wrote that "Ralph can be done with any tool that does not cap tool calls and usage," and his post also shows it running with Amp. The Thoughtworks Technology Radar (April 2026) notes that "Tools such as goose have implemented the pattern."

05

Can several Ralph loops share one Flux board?

+

Yes, if each loop has its own Ready column. Flux has no card locking or atomic claiming, so two loops reading the same column can pick the same card. Separate columns, or separate boards, keep them apart.

06

Does Flux run the loop for you?

+

No. Flux, task management for AI agent teams, is the board the loop reads and updates. You run the loop yourself, on your machine or in CI, with Claude Code or another agent that connects to the Flux MCP server or the REST API.

// One card per pass

Let the loop work the queue. Keep people on the review.

Put your Ralph loop's task list on a shared board, let each pass take one card over MCP, and check the work in Needs review before Done. Free to start, and agents that connect with an API key never take a seat.