Back to Blog

Claude Code /goal: how to set a goal it can actually finish

Alex Kim
10 min read
Claude Code /goal: how to set a goal it can actually finish

Last updated: November 13, 2026

TL;DR

Type /goal followed by a condition, and Claude Code keeps working, turn after turn, until a separate small model reads the conversation and agrees the condition holds. The condition is the whole skill: that evaluator "doesn't run commands or read files independently," so write one measurable end state, the command that proves it, and anything that must not change on the way.

  • ๐ŸŽฏ Set it. /goal all tests in test/auth pass and the lint step is clean starts work at once, with no separate prompt.
  • โœ๏ธ Make it provable. One end state, a stated check, and the constraints that matter, in up to 4,000 characters. Add "or stop after 20 turns" to bound it.
  • ๐Ÿ”“ Run it in auto mode for unattended turns. In Manual mode, Claude still stops to ask.
  • ๐Ÿ“Š Check and stop it. /goal on its own shows status; /goal clear ends it.
  • ๐Ÿค– Script it. claude -p "/goal ..." runs the whole loop in one invocation.

Before you start

/goal is part of Claude Code's hooks system, so three things decide whether it's available (goal docs):

  • The folder is trusted. It follows the same workspace trust rule as hooks in settings files.
  • Hooks aren't turned off. It's unavailable when disableAllHooks is true after settings precedence applies.
  • Managed settings allow it. It's also unavailable when allowManagedHooksOnly is set in managed settings.

You also want a task with "a verifiable end state." Anthropic's examples: migrating a module until every call site compiles and tests pass, implementing a design doc until every acceptance criterion holds, splitting a large file until each module is under a size budget, or working a labeled issue backlog until it's empty.

Step 1: Write a condition the evaluator can check

After every turn, Claude Code sends your condition and the conversation so far to the small fast model, which returns one of three verdicts: not yet met, met, or impossible. It judges only what Claude has already surfaced, so the proof has to appear in the transcript.

Anthropic lists three parts of a condition that holds up across many turns:

PartWeakStronger
One measurable end state"Make the auth module better""All tests in test/auth pass"
A stated check"Tests should work""npm test exits 0"
Constraints that matter(none)"No other test file is modified"

Put together: /goal all tests in test/auth pass, shown by npm test exiting 0, with no other test file modified, or stop after 20 turns. The last clause bounds the run. Claude reports progress against it each turn, and the evaluator judges it from the conversation like everything else.

Step 2: Set the goal

Run /goal with the condition. If a goal is already active, the new one replaces it, since a session holds one goal at a time.

Setting a goal starts a turn immediately, with the condition as the instruction. While it runs, a โ—Ž /goal active indicator shows how long it has been going, the transcript shows each verdict, and Ctrl+O shows the reason behind it.

Step 3: Let the turns run

Pick the permission mode first. A goal doesn't change it. In auto mode, tool calls are approved within each turn and /goal starts the next one, which is what makes a run unattended: Anthropic puts it as "auto mode removes per-tool prompts, and /goal removes per-turn prompts." In Manual mode, Claude still asks before any tool call your settings don't allow, such as the test command itself.

Then let the evaluator decide. Each verdict does one thing:

  • Not yet met: Claude keeps working and takes the reason as guidance.
  • Met: the goal clears and the transcript records it as achieved.
  • Impossible: the goal clears and the transcript records a failed entry with the reason.

One safeguard runs in the background. If Claude keeps answering the evaluator without using any tools for several turns in a row, Claude Code stops the loop, prints a warning and hands control back, with the goal still set.

Step 4: Check on it, and stop it

  • /goal with no argument shows the condition, how long it has run, the turns evaluated, the token spend and the evaluator's latest reason.
  • /goal clear ends it before it resolves. stop, off, reset, none and cancel work too, and /clear removes it along with the conversation.
  • Resuming a session restores a goal that was still active, with the turn count, timer and token baseline reset. A goal that was achieved or cleared doesn't come back.

Run a goal from a script

/goal works in non-interactive mode, the desktop app and Remote Control. In a script, setting a goal with -p runs the loop to completion in one invocation, and Anthropic's example is claude -p "/goal CHANGELOG.md has an entry for every PR merged this week".

With the default text output, nothing prints until the loop ends, so a long goal can look stuck. Switch the output format to stream-json with verbose output on to see each message as it runs, and press Ctrl+C to stop a goal before it resolves. Our guide to Claude Code automation covers the other flags a scripted run needs.

When a goal stops early

Not every failure ends a goal. Anthropic's docs sort them into three groups:

What happenedWhat the goal does
An error you have to fix: an authentication failure, an exhausted credit balance, a context overflow auto-compaction couldn't clear, or a model that isn't availableClears, with a warning that starts "Goal cleared after an unrecoverable error". Fix the cause and set it again
A failure that tends to clear by itself, such as an overloaded server or a dropped connectionStays set and retries on its own, then pauses after three automatic retries
A failure a retry would only repeat, such as a rate limit, a usage limit or a hook that ended the turnStays set and pauses, with a notice naming the cause

Background work changes the timing too. If a subagent or a background shell command is still running when a turn ends, the evaluation waits for the next turn that finishes without one. After 30 minutes of waiting, a check-in asks Claude to read the running tasks and fix or stop any that are stuck. The CLAUDE_CODE_GOAL_CHECKIN_MINUTES variable changes that interval, and 0 turns check-ins and automatic retries off.

/goal, /loop or a Stop hook

All three keep a session working. What differs is what starts the next turn (goal docs):

ApproachNext turn starts whenStops when
/goalThe previous turn finishesA model confirms the condition or judges it impossible, an error you have to fix clears it, or you clear it
/loopA time interval passesYou stop it, or Claude decides the work is done
Stop hookThe previous turn finishesYour own script or prompt decides

Under the hood, /goal is "a wrapper around a session-scoped prompt-based Stop hook." Use /goal for one task in one session. Write a Stop hook in your settings when the same check should apply to every session, or when you want a script rather than a model to decide. Our hooks guide shows how.

Troubleshooting

SymptomLikely causeFix
/goal isn't availableThe folder isn't trusted, disableAllHooks is on, or managed settings allow only managed hooksTrust the folder, or ask whoever manages your settings
The goal never clearsThe condition isn't something Claude's output can proveName the command and the result, such as a test run exiting 0
It keeps stopping to askThe session is in Manual modeSet the goal in auto mode, or allow the commands it needs
A scripted goal looks stuckDefault text output prints only the final answerUse the stream-json output format with verbose output
It stopped with the goal still setNo tool use for several turns, or a paused errorSend a message to start the next turn, or fix the named cause

Frequently asked questions

What does /goal do in Claude Code?

It sets a completion condition and keeps Claude working toward it without a prompt for each step. After every turn, a separate small model checks the conversation against the condition. The goal clears when the condition is met, when the model judges it impossible, or when an error you have to fix stops it.

How do I write a good /goal condition?

Give one measurable end state, the check that proves it, and the constraints that must hold, such as all tests in test/auth pass, npm test exits 0, and no other test file changes. The evaluator only reads the conversation, so the proof has to appear in Claude's output. Add a turn limit to bound it.

Does /goal run unattended?

Only in auto mode. A goal doesn't change your permission mode, so in Manual mode Claude still stops to ask before tool calls your settings don't allow. Auto mode approves tool calls within each turn, and /goal starts the next turn, so together they run without you.

What is the difference between /goal and /loop?

A goal starts the next turn as soon as the previous one finishes and stops when your condition holds. A loop starts the next turn on a time interval and suits repeated checks, such as watching CI. Use /goal for one task with a finish line and /loop for something you poll.

Why isn't /goal working in Claude Code?

It's part of the hooks system, so it's unavailable in a folder you haven't trusted, when disableAllHooks is on, or when managed settings allow only managed hooks. If it runs but never clears, the condition probably isn't something Claude's own output can prove.

Can I use /goal in a script?

Yes. Run claude -p with /goal and the condition as the prompt, and Claude Code runs the loop to completion in one invocation. Default text output prints only at the end, so use the stream-json output format with verbose output to watch it, and Ctrl+C to stop it.

Write the finish line down once

A good condition takes thought: which test command proves the work, which files must not change, what done means in this repository. Writing that down once, where Claude reads it, saves rewriting it for every goal. Our guide to compound engineering for Claude Code shows how to build those written rules up one fix at a time. For the other ways to run Claude Code without you, start with our Claude Code automation guide, and for the scheduling side, our guide to Claude scheduled tasks.

#claude-code#Automation#ai-agents#Goal#auto mode
Free assessment

Stop guessing. Score your first workflow.

Score one workflow in about five minutes. Nine questions, a grade, and the specific gap holding it back - no call required.