/goal in Claude Code: Stop Babysitting the Loop

Anthropic shipped /goal in Claude Code v2.1.139. The pitch is simple: you set a finish line, Claude keeps working across turns until it's crossed. No more typing "continue" every two minutes, no more clicking through tool approvals while you make coffee.

Codex shipped the same shape of feature a week earlier and the AI feed lost its mind for a few days. The Claude version is here now. This guide is the full breakdown: what it actually does under the hood, what makes a good goal condition, the use cases that land, and the gotchas everyone misses on day one.

What /goal actually is

Straight from the v2.1.139 changelog:

Added /goal command: set a completion condition and Claude keeps working across turns until it's met. Works in interactive, -p, and Remote Control. Shows live elapsed/turns/tokens as an overlay panel.

Mechanically: after each of Claude's turns, a small fast model reads the conversation transcript and judges whether your condition is met. Not met means Claude gets prompted to keep going automatically. Met means the goal clears and control returns to you.

It's autonomous looping with a verifiable exit, which is the part that matters. A loop without an exit condition is a chatbot in a hamster wheel. A loop with one is an agent that actually finishes work.

Check your version first

/goal needs v2.1.139 or newer. Confirm:

claude --version

If you're behind, update:

npm install -g @anthropic-ai/claude-code@latest

One more thing: /goal uses the hooks system internally. If you have disableAllHooks or allowManagedHooksOnly set in your settings, /goalwill tell you it can't run instead of silently hanging (that bug was fixed in v2.1.140). For most people this isn't an issue, but worth knowing if you work somewhere with locked-down managed settings.

The basic syntax

At the prompt:

/goal <your completion condition in plain english>

Example:

/goal all tests in the auth package pass and lint is clean

That's it. Claude takes a turn, the evaluator checks the transcript against your condition, and if it isn't met yet, Claude takes another turn. The overlay panel shows live elapsed time, turn count, and token usage so you can see what you're burning.

To cancel mid-flight, hit Esc or Ctrl+C. To replace the active goal with a new one, just run /goal again. One goal active per session.

What makes a good /goal condition

This is the part that decides whether /goal saves you an hour or burns 200k tokens spinning. The rule is short:

The condition has to be observable from what Claude writes in the transcript.

The evaluator is a separate model. It doesn't run your tests, it doesn't open your files, it doesn't check your dashboard. It reads the chat. So if Claude needs to prove the goal is met, Claude has to make it visible in its output.

Good conditions look like this:

• npm test passes and lint is clean (Claude can run both and paste the result)
• all 47 components migrated to the new Button API and verified with grep (verifiable by listing or grepping)
• the build succeeds with zero warnings and you've shown the final output (build output is text Claude can paste)
• every TODO in src/payments has been resolved or converted to a tracked issue (file-grep verifiable)

Bad conditions look like this:

• make the UI feel better (not observable)
• the deploy went through (only true if Claude actually deploys AND shows the result, not if it says "deploy initiated")
• the user is happy with the design (the evaluator can't ask the user)
• the bug is fixed (fixed by what measure?)

Rule of thumb: if you can't write the check in one sentence that mentions specific output, files, or commands, the goal isn't ready for /goal yet. Spend two minutes sharpening it before you spend an hour watching it spin.

Five use cases that actually work

1. Migrate-until-done

You're moving a codebase from one library to another. Class components to hooks, axios to fetch, moment to date-fns. The migration is mechanical, the verification is mechanical, but the volume is annoying.

/goal every file in src/ that imports moment has been migrated to date-fns. verify with: grep -r "from 'moment'" src/ returning zero results, and npm test passing.

2. Green-until-stable

Flaky test suite. You want Claude to fix the failures, run the suite, fix anything new that breaks, run again, until the whole thing is stable across three consecutive runs.

/goal npm test passes three consecutive runs with zero failures. fix any failing tests, then re-run. do not modify a test to make it pass without explaining why in the chat first.

3. Spec-to-implementation

You have a spec written. You want Claude to implement it end to end, with the acceptance criteria as the gate.

/goal every acceptance criterion in docs/spec-checkout.md is implemented and verified. for each criterion, paste the test you ran and the passing output. only mark the goal met when every criterion has been ticked off in the chat with evidence.

4. Refactor-to-budget

File got too big. You want it broken up into modules with no single file over a size limit, and the public API unchanged.

/goal no file in src/ exceeds 300 lines. the public exports from src/index.ts are unchanged (verify with diff). npm test still passes. show the final wc -l output for src/ before declaring done.

5. Build-your-own-goals

This one's the meta move and it's the most fun. You hand Claude a project, tell it to write its own goal condition, and then run it.

read CLAUDE.md and the open issues in TODO.md. propose three /goal conditions you could realistically achieve in one session, each with a clear verification step. ask me to pick one, then run /goal with the version i pick.

You stop being the one designing the loop. Claude designs it, you approve it, and then it runs.

The limits everyone hits

The evaluator can only see text. If your "done" lives outside the transcript (a Grafana dashboard, a deployed URL, a teammate's approval), /goal can't verify it. Either bring the proof into the chat (paste the curl output, log the dashboard reading), or don't use /goal for that task.

Claude can lie to itself.If you write a vague condition, the evaluator will accept vague proof. "The bug is fixed" is a free pass for Claude to declare victory after a single speculative edit. Sharp conditions force sharp proof.

One goal active per session. Running /goal again replaces the active one. There is no goal stack.

The evaluator waits for background work.v2.1.140 fixed an earlier bug where the evaluator would fire while background shells or delegated subagents were still running. Now it correctly waits. If you're on an older version and seeing weird premature exits, that's why.

Token cost compounds. Every extra turn is real money. The overlay panel shows the running total. If your goal is hitting 30+ turns, something is wrong with the condition, not the model.

Trusted workspaces only. Because /goal uses hooks, it runs in folders Claude Code trusts. If you opened the repo and got a trust dialog, accept it before running /goal.

/goal vs /loop vs auto mode

These get confused a lot:

• /goal loops Claude's turns until a completion condition is met. Goal-shaped.
• /loop reruns a prompt on a schedule (every 5 minutes, every hour). Time-shaped. Use for "check the deploy every 10 minutes," not "finish this task."
• Auto mode removes per-tool approval prompts within a turn. /goal removes per-turn approval between turns. They stack: auto mode + /goal = fully autonomous run.

Mental model: /loop is "keep doing this thing." /goalis "keep working until this is true." Auto mode is "stop asking me before every Bash call."

The move

Pick one mechanical task you do this week (a migration, a test suite green-up, a refactor pass) and write the goal condition before you write the prompt. If you can state the condition in one sentence with a specific check, /goalwill close the loop. If you can't, the task isn't ready for autonomy yet, and that's a useful signal in itself.

Stop babysitting the loop. Start designing the exit.