A completion condition, not a timer
/goal is Claude Code's way of keeping a session working toward a specific, verifiable end state without you re-prompting after every turn. You give it a condition in plain language; a separate small fast model checks the conversation against that condition after each turn Claude takes; if the condition doesn't hold yet, Claude starts another turn on its own. It's documented at code.claude.com/docs/en/goal, and it's built for work with a real finish line: migrating a module until every call site compiles and tests pass, working an issue backlog until the queue is empty, implementing a design doc until every acceptance criterion holds.
That's a different mechanism from anything scheduled. /goal doesn't wait on a clock; it starts the next turn the instant the previous one finishes, and it doesn't stop until a model actually confirms the condition, not until you decide to check back in.
Setting and checking a goal
One goal can be active per session, and the same command sets, checks, and clears it depending on what you pass:
/goal all tests in test/auth pass and the lint step is clean
Setting a goal starts a turn immediately, using the condition itself as the directive, so there's no need for a separate prompt afterward. While it's active, a ◎ /goal active indicator stays visible showing how long it's been running.
Run /goal alone to see the current state:
/goal
That shows the condition, how long it's been running, how many turns have been evaluated, current token spend, and the evaluator's most recent reason for its verdict. Press Ctrl+O at any point while a goal is active to see the full reasoning behind the latest verdict, not just the summary.
To stop one before it resolves:
/goal clear
stop, off, reset, none, and cancel all work as aliases for clear. Starting a fresh conversation with /clear removes an active goal too.
Writing a condition that actually works
The evaluator only judges what Claude has already surfaced in the conversation. It doesn't independently run commands or read files, so a condition has to be something Claude's own output can demonstrate directly. "All tests in test/auth pass" works because Claude runs the test command and the result lands in the transcript for the evaluator to read; a condition the evaluator can't observe from the transcript alone just stalls.
A condition that holds up across many turns tends to have three things:
- One measurable end state: a test result, a build exit code, a file count, an empty queue.
- A stated check: how Claude should prove it, such as "
npm testexits 0" or "git statusis clean." - Any constraints that matter: what must not change on the way there, for example "no other test file is modified."
Conditions can run up to 4,000 characters, and you can bound how long a goal is allowed to run by adding a clause directly, like or stop after 20 turns. Claude reports progress against that clause each turn, and the evaluator judges it from the conversation the same way it judges everything else.
How the evaluation loop actually works
/goal is a wrapper around a session-scoped prompt-based Stop hook. Every time a turn ends, Claude Code sends the condition plus the conversation so far to the small fast model configured for your provider (Haiku by default on the Claude API; check your provider page for the default elsewhere). That model returns one of three verdicts, each with a short reason:
- Not yet met: Claude keeps working, treating the reason as guidance for what to try next.
- Met: Claude Code clears the goal and records an achieved entry in the transcript.
- Impossible: the evaluator has judged the condition can never be satisfied. Claude Code clears the goal on its own and records a failed entry with the reason, so you don't need to clear it manually.
If a subagent or a background shell command is still running when a turn ends, evaluation is skipped for that turn and happens when the next one finishes instead. And if Claude spends several turns in a row replying to the evaluator without calling any tools, meaning genuinely no progress, Claude Code stops the loop, prints a warning, and returns control to you with the goal still set rather than continuing to spin.
To evaluate on a different model than your provider's default, set ANTHROPIC_DEFAULT_HAIKU_MODEL. Worth knowing before you touch that variable: Claude Code reads it everywhere it uses the small fast model, not only for /goal, so setting it also changes what conversation summarisation and other background functionality run on.
/goal vs /loop vs a Stop hook
All three keep a session running across turns without you re-prompting, but they answer a different question about when the next turn starts:
| Next turn starts when | Stops when | |
|---|---|---|
/goal | The previous turn finishes | A model confirms the condition is met or judges it impossible |
/loop | A time interval elapses | You stop it, or Claude decides the work is done |
| Stop hook | The previous turn finishes | Your own script or prompt decides |
/goal and a Stop hook both fire immediately after every turn rather than waiting on a clock, which is what separates them from /loop. The difference between the two is scope and reuse: /goal is a session-scoped shortcut, typed once and active only for the current session, while a Stop hook lives in your settings file, applies to every session within its scope, and can run a script for a deterministic check or a prompt for one a model judges, the same mechanism /goal itself is built on.
It's worth being precise about what /goal doesn't do, too. Auto mode on its own approves tool calls within a single turn, but it doesn't start a new turn once Claude judges the work done. /goal adds a separate evaluator on top that decides completion after every turn, using a fresh model rather than the one that did the work. The two solve adjacent problems and pair naturally: auto mode removes prompts within a turn, /goal removes the need for you to kick off the next one.
Running it non-interactively
/goal works the same way through non-interactive mode, the desktop app, and Remote Control. Passed with -p, it runs the whole loop to completion in a single invocation:
claude -p "/goal CHANGELOG.md has an entry for every PR merged this week"
With plain text output, nothing prints until the run actually ends, so a goal spanning many turns can look stuck from the outside. Add --output-format stream-json --verbose to see each message as the loop progresses instead of waiting on a silent terminal. Ctrl+C interrupts a non-interactive goal before it resolves, the same as any other running command.
Resuming a session with an active goal
A goal still active when a session ends is restored automatically on --resume or --continue. The condition itself carries over unchanged, but the turn count, elapsed timer, and token-spend baseline all reset to zero on resume. A goal that already resolved, whether achieved or cleared, before the session ended is not restored; only a genuinely still-active one comes back.
Requirements and restrictions
/goal is gated by the same workspace trust rule as hooks generally, since the evaluator runs as part of the hooks system under the hood. It's unavailable when disableAllHooks is true after settings precedence resolves, and when an organisation sets allowManagedHooksOnly in managed settings. In both cases Claude Code tells you why the command isn't available rather than silently doing nothing, which is worth knowing before assuming a bug.
Where /goal fits with skills
Nothing about /goal changes how Agent Skills are discovered or invoked. A skill Claude is already allowed to call on its own keeps firing normally during a /goal loop, the same as during any other turn. What changes is only the mechanism deciding when Claude stops working and hands control back, which matters most for skills built around a long, multi-step task with a clear finish line, like a migration or a backlog sweep, rather than a single-shot action.
Where to go next
For scheduling work on an interval instead of toward a condition, see Claude Code Routines vs /loop. For running /goal turns fully unattended, Claude Code's auto mode covers what gets approved automatically and what still requires you. If you're coordinating a /goal loop across several agents rather than one session, see what Claude Code's agent teams feature does. Browse the current catalogue at getclaudeskills.com/platforms/claude-code.
