Claude Code /goal: Set a Goal and Let It Keep Working
Claude Code /goal sets a finish line and Claude keeps working until a separate model says it's met. How to set, check and clear a goal, plus /loop and cost.
Josh Pocock8 min read
AI Coding
Claude Code /goal
Stride AI Academy
The Claude Code /goal command sets a completion condition, and Claude keeps working toward it without you prompting each step. After every turn, a separate small model checks whether the condition holds. If it doesn't, Claude starts another turn. The goal clears itself when the condition is met, when the evaluator judges it impossible, or when an error you have to fix stops the run.
This guide covers how to set, check and clear a goal, how to write a condition that works, how evaluation and cost work, and how /goal compares with /loop, Stop hooks and routines. Everything here was checked against Claude Code's /goal docs and guidance on getting good results on November 22, 2026.
What /goal does in Claude Code
Normally Claude stops when it thinks the work looks done. /goal adds a second opinion. Each time Claude finishes a turn, Claude Code sends your condition and the conversation so far to your configured small fast model. It returns one of three verdicts:
| Verdict | What happens |
|---|---|
| Not yet met | Claude keeps working and uses the evaluator's reason as guidance for the next turn |
| Met | The goal clears and an achieved entry goes in the transcript |
| Impossible | The goal clears and a failed entry goes in the transcript, with the reason |
The docs say /goal is a wrapper around a session-scoped, prompt-based Stop hook. Completion is decided by a fresh model rather than the one doing the work.
Good uses, from the docs:
- Migrating a module to a new API until every call site compiles and tests pass
- Implementing a design doc until all acceptance criteria hold
- Splitting a large file until each module is under a size budget
- Working through a labeled issue backlog until the queue is empty
How to set a goal
Type /goal and the condition:
/goal all tests in test/auth pass and the lint step is cleanSetting a goal starts a turn straight away, with the condition as the instruction, so you don't need a separate prompt. One goal can be active per session, and a new one replaces the old. A ◎ /goal active indicator shows how long it has been running.
While it runs, the transcript shows each verdict. Press Ctrl+O to see the reason behind one.
Goals don't change your permission mode
A goal keeps Claude taking turns, but it doesn't approve tool calls. In manual mode, Claude still asks before commands your settings don't already allow, such as the test command above. To let goal turns run unattended, run /goal in auto mode. The docs put it neatly: auto mode removes per-tool prompts, and /goal removes per-turn prompts.
How to write a condition that works
The evaluator doesn't run commands or read files. It only judges what Claude has shown in the conversation. So write the condition as something Claude's own output can prove. "All tests in test/auth pass" works because Claude runs the tests and the result lands in the transcript.
The docs say a strong condition has:
- One measurable end state: a test result, a build exit code, a file count, an empty queue
- A stated check: how Claude proves it, such as "
npm testexits 0" or "git statusis clean" - Constraints that matter: what must not change on the way, such as "no other test file is modified"
Conditions can be up to 4,000 characters. To cap how long a goal runs, put a turn or time clause in it:
/goal npm test exits 0 with no other test file modified, or stop after 20 turnsClaude reports progress against that clause each turn, and the evaluator judges it from the conversation.
How to check and clear a goal
Run /goal with nothing after it to see the status:
/goalThe status shows the condition, how long it has run, how many turns have been evaluated, the current token spend and the evaluator's latest reason. If no goal is active but one was achieved earlier, you see that one's duration, turns and spend instead.
To stop a goal early:
/goal clearClaude prints Goal cleared: and the condition, or No goal set. The docs accept stop, off, reset, none and cancel as aliases. Running /clear to start a new conversation removes the goal too.
Resuming a session
If a goal was still active when a session ended, Claude Code restores it when you resume with --continue, --resume or the session picker. The condition carries over, but the turn count, timer and token-spend baseline reset.
Run a goal from a script
/goal works in non-interactive mode, the desktop app and through Remote Control. With -p, the whole loop runs in one call:
claude -p "/goal CHANGELOG.md has an entry for every PR merged this week"With the default text output, you only see Claude's final response, so a long goal can look stuck. Add streaming to watch it:
claude -p "/goal CHANGELOG.md has an entry for every PR merged this week" --output-format stream-json --verbosePress Ctrl+C to stop it.
When a goal stops on its own
Some failures clear the goal, and the warning starts with Goal cleared after an unrecoverable error. The docs list:
- An authentication failure, when Claude Code manages its own credentials
- A disk too full to renew your claude.ai login
- An exhausted credit balance
- A context overflow that auto-compaction couldn't clear
- A model that isn't available
Fix the cause, then set the goal again.
Other errors leave the goal set. On v2.1.269 or later, an overloaded server or dropped connection gets an automatic retry with a Goal still active notice, up to three times. A rate limit, a claude.ai usage limit or a hook that ended the turn pauses it with a Goal paused notice. Send any message to start the next turn.
If Claude keeps answering the evaluator without making progress, with no tool use for several turns in a row, Claude Code stops the loop, warns you and hands control back with the goal still set.
Background work and check-ins
If a subagent or background shell command is still running when a turn ends, the evaluation waits for the next turn with nothing running. After 30 minutes of waiting, Claude Code runs a check-in: it lists the running tasks and asks Claude to read their output, keep waiting or fix what's stuck. Later check-ins come at longer intervals. Set CLAUDE_CODE_GOAL_CHECKIN_MINUTES to change the first interval, or to 0 to turn off check-ins and automatic retries.
What /goal costs
Evaluation tokens are billed on top of the main turns. The evaluator runs on the small fast model for your provider. To evaluate on a different model, set ANTHROPIC_DEFAULT_HAIKU_MODEL, but the docs warn that this also changes the haiku alias and the model used for session titles and other background tasks.
Anthropic's guidance page lists a goal's check after every turn as one of the things that keep sending requests while you aren't typing, alongside /loop and subagents. Use /goal for real work with a clear finish line, not as a default. The Claude Code cost calculator helps you estimate a month.
/goal vs /loop, Stop hooks and routines
| Approach | Next turn starts when | Stops when |
|---|---|---|
/goal |
The previous turn finishes | A model says the condition is met or impossible, an error you must fix, or /goal clear |
/loop |
A time interval passes | You stop it, or it ends on its own |
| Stop hook | The previous turn finishes | Your script or prompt decides |
Use /goal when there's a finish line. Use /loop when you want the same prompt repeated on a timer, such as checking a deploy every 10 minutes. A Stop hook lives in your settings and applies to every session in its scope, and a command hook gives you a deterministic check instead of a model's judgment. Our hooks tutorial shows how. All three keep the current session going. For work that should run with your laptop closed, use Claude routines.
Anthropic's guidance page says you rarely need /goal while you're watching. It matters most in long background runs, where Claude sometimes ends a turn with a progress summary while items are still open, and the goal sends it back. Our Claude Code workflow shows where it fits next to a plain prompt and a Stop hook.
Requirements
/goal follows the same workspace trust rule as hooks in settings files, because the evaluator is part of the hooks system. It's unavailable when disableAllHooks is true, or when allowManagedHooksOnly is set in managed settings.
Learn to build with Claude Code
The Stride AI Coding course teaches Claude Code and Codex for building client tools, written for non-programmers, with weekly live calls to review your builds. Many of the free guides cover Claude Code setups, and the Claude Code community is where members compare theirs.
FAQ
What does /goal do in Claude Code?
It sets a completion condition. After every turn, a separate small model checks the condition against the conversation, and Claude keeps working until it's met, judged impossible, or stopped by an error you have to fix.
How do I stop a goal in Claude Code?
Run /goal clear. stop, off, reset, none and cancel also work, and /clear removes the goal along with the conversation. In a -p run, press Ctrl+C.
Does /goal run without permission prompts?
No. A goal doesn't change your permission mode. In manual mode Claude still asks before tool calls your settings don't allow, so run /goal in auto mode for unattended turns.
What's the difference between /goal and /loop?
/goal works toward a finish line and starts the next turn as soon as the last one ends. /loop repeats a prompt on a time interval until you stop it.
Does /goal cost extra?
The evaluation tokens are billed on top of the main turns, and the goal keeps Claude taking turns until it resolves. Add a clause such as "or stop after 20 turns" to cap a long run.
Can I use /goal in a script?
Yes. claude -p "/goal <condition>" runs the loop to completion in one call. Add --output-format stream-json --verbose to see each message as it runs.