Define the Finish Line
Claude Code’s /goal uses a separate evaluator of conversation evidence to guide continuation. The evaluator cannot independently run checks, and documented stopping and error conditions still apply.
Long coding tasks often end up as a sequence of prompts asking the agent to continue. A goal mechanism can automate that continuation, but the difficult part remains defining an observable result.
Claude Code’s /goal sets a condition and can continue across turns while a separate evaluator assesses it. The current documentation describes additional stopping and error states, so treat this as a continuation mechanism rather than a guarantee that the job will finish.
But there's a twist most people miss for the first hour, and it's the whole point of this post.
What it actually is
/goal <condition> sets the condition and immediately starts a turn — the condition is the prompt, no separate message needed. A ◎ /goal active chip tracks elapsed time. /goal on its own shows status: the condition, how long it's run, how many turns the evaluator has judged, the token spend, and the evaluator's last reason. /goal clear stops it (stop, off, reset, none, cancel all work; so does /clear). One goal per session; the condition can run up to 4,000 characters.
A session-scoped evaluator reads the condition and conversation. It can return not yet met, met or impossible. Its provider-configured small model does not independently run tools. The distinction matters: it evaluates the evidence visible in the transcript.
It runs headless, too: claude -p "/goal CHANGELOG.md has an entry for every PR merged this week" runs the continuation loop within one invocation, subject to documented stopping, error and resource-limit behavior. And a goal still active when you quit is restored on --resume or --continue — though the turn counter, the timer, and the token baseline all reset, which matters in a minute.
The manual version
A custom Stop hook can call a deterministic acceptance check. Native /goal offers a convenient model-evaluated continuation rule. Both can reduce repeated prompting, but they do not provide the same verification boundary.
An exit code is useful only when the command checks the right behavior and its result is trustworthy. A model reading a transcript adds another interpretation step. Preserve direct acceptance checks where the outcome matters.
The evaluator is blind
The evaluator assesses the conversation evidence available to it. It cannot independently inspect the repository or run checks, but command results surfaced in the transcript can support its decision.
Specify both the desired result and the evidence to surface. A condition such as “the tests pass” can be evaluated when the relevant test result appears in the transcript. A claim without supporting evidence leaves completion unestablished.
The fix is to phrase the condition around observable output and make Claude surface it. Not "the tests pass" but "npm test was run this turn and its output shows 0 failures." Not "the file is clean" but "ruff check src/ printed All checks passed." You're defining done in terms of evidence that lands in the transcript where a blind model can read it. Make Claude show its work, because the judge only grades what's on the page.
The shoebox problem
Consider a hypothetical game implementation whose only acceptance checks are a successful build and passing unit tests. It can meet those checks while the controls or layout remain unusable.
The lesson is to make the specification cover the actual experience: interaction, layout and representative play behavior as well as compilation. A test suite is a chosen sample of requirements, not a complete definition of quality.
Stopping and limits
Use /goal clear to remove an active goal; current documentation also describes automatic clearing for met, impossible and certain failure states. A time or turn clause judged from the transcript is not the same as an externally enforced resource limit. Use supported CLI limits or a supervisor when a hard cap is required.
Test failure and cancellation paths before a long run. Include unavailable credentials, missing tools, exhausted budgets and an unreachable acceptance condition. Confirm what remains active after resume rather than assuming a stopped process cleared the goal.
How to actually run one
The setup that makes /goal sing isn't the command — it's the scaffolding around it:
Record the applicable build and acceptance commands in the project instructions. Hooks can surface relevant results automatically, provided they are reliable and correctly scoped. Permissions remain a separate control; unattended execution should use explicitly allowed operations within the intended environment.
Then the docs' examples land: migrate a module until every call site compiles and tests pass; implement a design doc until all acceptance criteria hold; split a 2,000-line file until each module is under a size budget; burn down a labeled issue queue until it's empty. They all share one trait — a finish line you could hand to a stranger and they'd know the moment you crossed it.
Route, don't marry
Similar command names across agent products do not imply matching persistence, budgets or evaluation behavior. Check the specific product and version, and test the stop and resume paths your controller depends on.
The skill that's left
Strip it down and /goal is doing something quietly subversive to how we work. For two years the valuable skill was prompt-craft — the right words to get the model moving. /goal doesn't care about your words. It cares whether you can name the finish line in a way a machine can check. A prompt can be open-ended because you read the output and decide it's good enough. A condition can't — there's no human in the loop to be reasonable about it.
The remaining engineering skill is defining done precisely enough to test. Native continuation can reduce prompting, while independent checks establish whether the requested behavior is present.
Hot takes
The evaluator judges available conversation evidence without independently checking the system. Missing evidence leaves completion unestablished; it does not prove that the work did not occur.
A green build is a proxy. Make a proxy a target and the agent ships you a shoebox. Goodhart's law now has a CLI.
Clearing a goal, interrupting a process and enforcing an external budget are different controls. Use the one appropriate to the desired boundary and verify its effect.
/goal is a session-scoped Stop hook with a friendlier face. If you've ever written a done_check.sh, you already understood the feature — you just typed it differently.
Prefer evidence from a protected check of the accepted revision over a model’s summary. Determinism alone does not prevent a worker from changing an unprotected test or its inputs.
Sources: Claude Code goals; Claude Code CLI reference. Documentation checked September 20, 2026.
