AI Coding

Claude Code /goal vs /loop vs Ralph Loop: Goal-Based Development Explained (2026)

Claude Code has four ways to keep working after a turn ends: /goal, /loop, the Ralph loop plugin, and a Stop hook. They differ in one thing that matters: what decides the work is finished. This guide explains how each one works, how to write a goal condition that actually resolves, and how to keep an unattended run from burning your budget.

Gurram Poorna Prudhvi

AI Engineering Lead

Intermediate
Nov 20, 2026
11 min read
FOUR WAYS TO KEEP CLAUDE CODE WORKINGthe difference is what decides the work is finished/GOALwork until a condition holdsbuilt in, one per sessiona small model checksreads the conversation onlyclears itself when metbest for: build until tests pass/LOOPrepeat a prompt on a timerbuilt inruns every N minutessame session each timestops when you stop itbest for: polling CI or a deployRALPH LOOPre-feed the same promptplugin, Anthropic marketplaceexact completion phrase--max-iterations cap/cancel-ralph to stopbest for: the Ralph techniqueSTOP HOOKyour script decideslives in settings.jsonexit code 2 blocks the stopapplies to every sessiondeterministicbest for: rules with no exceptionswhichever you pick: one checkable end state, and a cap on turns or spendaiengineerinsights.com · from Anthropic's Claude Code docs and the ralph-loop plugin README, checked Nov 18 2026

TL;DR — /goal vs /loop vs Ralph loop: use /goal to keep Claude working until a condition is met; a separate model checks it after every turn. Use /loop to repeat a prompt on a timer, for polling. The Ralph loop plugin re-feeds the same prompt until Claude prints an exact phrase, and needs --max-iterations. A Stop hook is the deterministic option: your script decides. For most "keep going until it works" jobs, the built-in /goal is now the place to start. Write the condition as one end state Claude's own output can prove, and add "or stop after N turns".

Explore this article with

1. What Is Goal-Based Development in Claude Code?

Normally Claude Code works for one turn and hands control back when it judges the work done. Goal-based development changes who makes that call. You state what "done" means once, and something other than the working model checks it after every turn. If the answer is "not yet", Claude starts another turn without waiting for you.

This is the idea behind the Ralph Wiggum technique, which Geoffrey Huntley summed up as "Ralph is a Bash loop": feed an agent the same prompt again and again and let it improve its own work through the files it leaves behind. Claude Code now has that built in as /goal, with a checker attached.

2. /goal vs /loop vs Ralph Loop vs a Stop Hook

/goal/loopRalph loopStop hook
What starts the next turnThe previous turn endsA time interval passesThe previous turn endsThe previous turn ends
What decides it is doneA separate small model reads the conversation and checks your conditionYou stop it, or Claude decides the work is doneClaude prints your exact completion phrase, or the iteration cap is hitYour script's exit code
Where you set itTyped in the sessionTyped in the sessionTyped in the session, after installing the pluginA settings file
ScopeThis session onlyThis session onlyThis session onlyEvery session in that settings scope
Deterministic?No: a model judgesNoPartly: exact string match plus a hard capYes, with a command hook
Built in?YesYesPlugin from Anthropic's marketplaceYes

One clarification, because the names invite confusion: /loop did not become /goal. Both exist. /loop is about time ("every 15 minutes"), and /goal is about a condition ("until the tests pass"). Auto mode is a third thing: it removes permission prompts within a turn but does not start a new one.

3. How Does /goal Work?

Type /goal followed by a condition. That starts a turn at once, with the condition as the instruction. Under the hood it is a session-scoped Stop hook that asks a model to judge. Each time Claude finishes a turn, Claude Code sends the condition and the conversation so far to your small fast model, which returns one of three verdicts:

  • • Not yet met: Claude keeps working, and takes the reason as guidance for the next turn.
  • • Met: the goal clears and the transcript records it as achieved.
  • • Impossible: the goal clears and the transcript records why.

The detail that decides whether a goal works: the checker does not run commands or read files. It only sees what Claude has already put in the conversation. A condition about something that never shows up there cannot be confirmed, however true it is.

/goal            # show the condition, time running, turns, token spend, last reason
/goal clear      # stop it (also: stop, off, reset, none, cancel)
Ctrl+O           # see the reason behind each verdict
  • • One goal per session. A new one replaces the old one.
  • • /clear removes an active goal. Resuming a session restores one that was still active.
  • • If a subagent or background command is still running when a turn ends, the check is skipped until that work finishes.

4. How to Write a Goal Condition That Resolves

A condition that holds up over many turns has three parts:

  • • One measurable end state: a test result, a build exit code, a file count, an empty queue.
  • • A stated check: the command that proves it, so its output lands in the conversation.
  • • The constraints that matter: what must not change on the way there.
ConditionVerdict
make the auth module betterNo end state, nothing to check
all tests passWhich tests, proven how? Claude could also delete a failing test
uv run pytest tests/auth exits 0, with no file under tests/ modified, or stop after 20 turnsOne end state, a stated check, a constraint, and a cap
every call to old_logger in app/ is replaced and rg old_logger app/ returns nothingThe check is a command whose output appears in the conversation
CHANGELOG.md has one entry for every PR merged since the last tag, listed by gh pr listNames the source of truth, so the checker can compare

Add a cap in the condition itself, such as or stop after 20 turns. Claude reports progress against it each turn and the checker reads that. The condition can be up to 4,000 characters, so there is room to be specific.

The constraint line is the one people skip. "Tests pass" can be satisfied by weakening the tests. If the tests are the spec, say so: no file under tests/ may be edited.

Get the AI engineering newsletter

Practical, engineering-first breakdowns on AI agents, LLMs, and breaking into the field — plus the free roadmap PDF when you join. No spam.

By subscribing you agree to receive emails from AI Engineer Insights. Unsubscribe anytime. See our Privacy Policy.

5. When Should You Use /loop?

/loop runs a prompt repeatedly while the session stays open. Give it an interval and a prompt:

/loop 15m check CI on this branch; if it is red, read the failing job's log, fix it and push
  • • Leave out the interval and Claude paces itself between runs.
  • • Leave out the prompt and it runs the built-in maintenance prompt, or your loop.md.
  • • Each run is another turn in the same session, so do not leave one going inside a long conversation: every run re-reads all of it.
  • • /proactive is an alias.

Use it for watching something that changes without you: a deploy, a CI run, a queue. For work that should happen while your laptop is closed, /schedule sets up a cloud task on a timer.

6. What Is the Ralph Loop Plugin, and Do You Still Need It?

The Ralph loop plugin is Anthropic's packaging of the Ralph Wiggum technique. Older posts call it ralph-wiggum. It uses a Stop hook to catch Claude's attempt to finish and feed the same prompt back in. The prompt never changes; Claude sees its own earlier work in the files and git history and builds on it.

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

/ralph-loop "Build a REST API for todos: CRUD, input validation, tests.
Output <promise>COMPLETE</promise> when every test passes." \
  --completion-promise "COMPLETE" --max-iterations 30

/cancel-ralph
  • • --max-iterations defaults to unlimited. Always set it.
  • • --completion-promise is an exact string match, so it cannot tell "finished" from "gave up". The plugin's own README says to treat the iteration cap as the main safety net.
  • • Nothing independent checks the claim. Claude can print the phrase when the work is not done.

That last point is the real difference from /goal, where a fresh model judges the condition and the working model's word is not enough. For most jobs, start with /goal. Ralph loop still fits when you want the same prompt re-read every round with a hard iteration count, or when you already have prompts written for it.

7. The Deterministic Option: a Stop Hook

A goal is judged by a model, so it can be wrong. When "done" must mean the test suite really passed, put the check in a Stop hook. Your command runs every time Claude tries to finish; exit code 2 blocks the stop and sends the error output back.

// .claude/settings.json
{
  "hooks": {
    "Stop": [
      { "hooks": [ { "type": "command", "command": "uv run pytest -q 1>&2 || exit 2" } ] }
    ]
  }
}

The two combine well: a goal to say what you want, a Stop hook to enforce the part that cannot be argued with. If a Stop hook blocks eight stops in a row with no tool call between them, Claude Code ends the turn anyway. More on where hooks fit in Claude Code best practices.

8. Running a Goal Unattended Without Burning Your Budget

  • • Permission mode: a goal does not change it. In Manual mode Claude still stops to ask before commands your settings do not allow. Run the goal in auto mode, with deny rules for what must never happen.
  • • A cap: put "or stop after N turns" in the condition. With -p you can also pass --max-turns or --max-budget-usd.
  • • Watch the spend: /goal with no argument shows turns and token spend so far. Every turn re-sends the conversation, and the check after each turn is one more small-model call.
  • • Limit the blast radius: run it in a worktree (claude -w name) on its own branch, and have a person approve the merge.
  • • Start small: try the goal on one module before the whole codebase.

From a script, a goal runs to completion in one call:

claude -p "/goal CHANGELOG.md has an entry for every PR merged this week" \
  --output-format stream-json --verbose

With plain text output the final answer only prints when the loop ends, which can look stuck. The streaming format shows each message as it happens.

9. Why Did My Goal Stop or Never Finish?

What you seeWhyWhat to do
Goal pausedA failure a retry would repeat: a rate limit, a usage limit, a hook that ended the turnWait or fix the cause, then send any message
Goal still active (retrying)A failure that tends to clear by itself, such as an overloaded server. After three automatic retries it pausesNothing, or send a message to retry now
Goal cleared after an unrecoverable errorSign-in failure, exhausted credit, a model that is unavailable, context that could not be compactedFix the cause and set the goal again
Judged impossibleThe checker decided the condition can never be metRead the reason, then rewrite the condition
Loop stopped, goal still setClaude answered the checker for several turns without using a toolSend a prompt that unblocks it
Never resolvesThe condition depends on something that never appears in the conversationRewrite it as something Claude's own output can show

The last row is the common one. If the condition is "the client approved the design" or "the staging site looks right", nothing in the conversation can prove it, and the goal keeps saying "not yet". Rewrite it as a command whose output Claude can show.

10. FAQ

What is the difference between /goal and /loop in Claude Code?

/goal keeps Claude working until a condition you write is met, and a separate model checks that condition after every turn. /loop repeats a prompt on a time interval while the session is open and stops when you stop it. Use /goal for building until something passes and /loop for polling something that changes over time.

What is the Ralph loop in Claude Code?

The Ralph loop is a technique where an agent is fed the same prompt repeatedly and improves its work through the files it leaves behind. In Claude Code it is available as the ralph-loop plugin from Anthropic's marketplace, which uses a Stop hook to re-feed the prompt until Claude prints a completion phrase or an iteration cap is reached.

Does /goal replace the Ralph loop plugin?

For most uses, yes. /goal is built in, needs no plugin, and has an independent model check the condition, while the Ralph loop trusts Claude to print a completion phrase. The plugin is still useful when you want the identical prompt re-read each round with a hard iteration limit.

How do I write a good /goal condition?

State one measurable end state, the command that proves it, and anything that must not change, then add a cap such as "or stop after 20 turns". The checker only reads the conversation, so the proof has to be something Claude's own output shows, such as a test command exiting with 0.

How do I stop a goal in Claude Code?

Run /goal clear. The words stop, off, reset, none and cancel work too, and /clear also removes an active goal. In a non-interactive run started with claude -p, press Ctrl+C. To stop a Ralph loop, run /cancel-ralph.

Does /goal cost more than a normal session?

It can. Each extra turn re-sends the conversation, and each check is one more call to the small fast model. The check itself is cheap; the turns are what add up. Run /goal with no argument to see turns and token spend, and put a turn limit in the condition.

11. Sources

Checked against Anthropic's Claude Code docs and the ralph-loop plugin README (v1.0.1) on November 18, 2026. Examples are ours. Behaviour such as retries and check-ins depends on your Claude Code version, so run /release-notes if something here does not match.

Found this useful? Share it.

Share:

Related Articles