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 | /loop | Ralph loop | Stop hook | |
|---|---|---|---|---|
| What starts the next turn | The previous turn ends | A time interval passes | The previous turn ends | The previous turn ends |
| What decides it is done | A separate small model reads the conversation and checks your condition | You stop it, or Claude decides the work is done | Claude prints your exact completion phrase, or the iteration cap is hit | Your script's exit code |
| Where you set it | Typed in the session | Typed in the session | Typed in the session, after installing the plugin | A settings file |
| Scope | This session only | This session only | This session only | Every session in that settings scope |
| Deterministic? | No: a model judges | No | Partly: exact string match plus a hard cap | Yes, with a command hook |
| Built in? | Yes | Yes | Plugin from Anthropic's marketplace | Yes |
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.
- •
/clearremoves 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.
| Condition | Verdict |
|---|---|
| make the auth module better | No end state, nothing to check |
| all tests pass | Which 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 turns | One 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 nothing | The 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 list | Names 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.
- •
/proactiveis 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-iterationsdefaults to unlimited. Always set it. - •
--completion-promiseis 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
-pyou can also pass--max-turnsor--max-budget-usd. - • Watch the spend:
/goalwith 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 --verboseWith 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 see | Why | What to do |
|---|---|---|
| Goal paused | A failure a retry would repeat: a rate limit, a usage limit, a hook that ended the turn | Wait 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 pauses | Nothing, or send a message to retry now |
| Goal cleared after an unrecoverable error | Sign-in failure, exhausted credit, a model that is unavailable, context that could not be compacted | Fix the cause and set the goal again |
| Judged impossible | The checker decided the condition can never be met | Read the reason, then rewrite the condition |
| Loop stopped, goal still set | Claude answered the checker for several turns without using a tool | Send a prompt that unblocks it |
| Never resolves | The condition depends on something that never appears in the conversation | Rewrite 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
- • Claude Code docs — Keep Claude working toward a goal
- • Claude Code docs — Commands (/goal, /loop, /schedule)
- • Claude Code docs — Hooks guide
- • Claude Code docs — Best practices (running without you)
- • ralph-loop plugin README, Anthropic's official marketplace
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.