Claude Code /goal: keep Claude working until a condition is met

What does /goal do in Claude Code?

/goal sets a completion condition, and Claude Code keeps starting new turns until a separate model confirms that the condition holds. You type something like /goal all tests in test/auth pass and the lint step is clean, Claude starts working at once, and after every turn an evaluator decides whether to hand control back or keep going.

The command shipped in Claude Code v2.1.139 during the week of 11 May 2026. Under the hood it is a session-scoped prompt-based Stop hook, so it is the quick version of something you could build yourself in hooks.

A goal clears in one of three ways, per the official /goal docs:

• The evaluator returns Met, and the transcript records an achieved entry.
• The evaluator returns Impossible, and the transcript records a failed entry with the reason.
• A turn fails on an error you have to fix, such as an exhausted credit balance.

Good fits are jobs with a checkable end state: migrating a module until every call site compiles and tests pass, implementing a design doc until each acceptance criterion holds, splitting a large file until each module is under a size budget, or working a labeled issue queue until it is empty.

How do you write a goal condition that works?

The evaluator does not run commands or read files. It reads only what Claude has surfaced in the conversation. So write a condition that Claude's own output can prove.

A condition that holds up over many turns has three parts:

1. One measurable end state: a test result, a build exit code, a file count, an empty queue.
2. A stated check: how Claude proves it, such as "npm test exits 0" or "git status is clean".
3. Constraints: what must not change on the way, such as "no other test file is modified".

Illustrative weak and strong versions (examples written for this page, not taken from the docs):

The condition can be up to 4,000 characters. To cap how long it runs, add a clause such as or stop after 20 turns. Claude reports progress against that clause each turn and the evaluator judges it from the transcript.

How is /goal different from /loop, auto mode and a Stop hook?

They solve different problems, and two of them combine well.

/loop is for polling on a timer, such as checking a deploy every 10 minutes. A Stop hook lives in a settings file and applies to every session in its scope; /goal is typed once and lasts only for the current session.

Auto mode is the natural partner. A goal does not change your permission mode, so in Manual mode Claude still stops to ask before tool calls your settings do not allow. The docs put it plainly: "auto mode removes per-tool prompts, and /goal removes per-turn prompts." For a goal that runs unattended, start it in auto mode.

The same idea exists in other agents. Codex describes its goal as "a persistent objective that ChatGPT works toward until it finishes the task, pauses, or needs more input" (Codex slash commands), and Antigravity CLI lists /goal <objective> to "Run autonomously until the goal is verified complete, without intermediate pauses" (CLI reference). See the Codex slash commands guide and the Antigravity CLI guide.

How do you check, clear or resume a goal?

One goal can be active per session, and the same command does everything:

/goal <condition>   set a goal, or replace the active one
/goal               show status
/goal clear         remove the active goal

While a goal runs, a ◎ /goal active indicator shows how long it has been going, and each verdict appears in the transcript. Press Ctrl+O to see the reason behind a verdict. /goal with no argument shows the condition, elapsed time, turns evaluated, token spend and the evaluator's latest reason.

/goal clear prints Goal cleared: and the condition, or No goal set. The aliases stop, off, reset, none and cancel work too, and /clear removes the goal with the conversation.

When you resume a session with --continue, --resume or the session picker, Claude Code restores a goal that was still active. It keeps the condition but resets the turn count, timer and token baseline, and it does not restore a goal that was already achieved or cleared.

Can you run /goal headless with claude -p?

Yes. /goal works in non-interactive mode, the Desktop app and Remote Control. With -p, the loop runs to completion in one invocation:

claude -p "/goal CHANGELOG.md has an entry for every PR merged this week"

With the default text output, only Claude's final response prints, so a long goal can look stuck. Stream each message instead:

claude -p "/goal npm test exits 0 and git status is clean" \
  --output-format stream-json --verbose

Press Ctrl+C to stop it early. A -p run has nobody to answer a permission prompt, so decide which tools it may use before you start. The headless guide covers the flags for that and for CI.

What does /goal cost, and what makes it stop early?

Each evaluation sends the condition and the conversation to your configured small fast model. The docs say evaluation tokens are "typically negligible compared to main-turn spend". What costs money is the extra working turns, which is why a turn or time bound in the condition matters. To evaluate on a different model, set ANTHROPIC_DEFAULT_HAIKU_MODEL, but note that Claude Code then uses that model everywhere it uses the small fast model, including background summarization.

A goal can stop or pause before it is met:

• No progress: if Claude answers the evaluator with no tool use for several turns in a row, Claude Code stops the loop, warns you and keeps the goal set. Evaluation resumes after your next prompt.
• Errors you have to fix: an authentication failure (when Claude Code manages its own credentials), an exhausted credit balance, a context overflow that auto-compaction could not clear, or an unavailable model. Claude Code clears the goal with a warning that starts Goal cleared after an unrecoverable error.
• Other errors: in interactive sessions on v2.1.269 or later, temporary failures such as an overloaded server retry automatically with a Goal still active notice, and pause after three retries. Rate limits and usage limits pause the goal with a Goal paused notice.
• Background work: if a subagent or background shell is still running when a turn ends, evaluation waits. After 30 minutes Claude Code checks in on the running tasks, then backs off to 1 hour, then every 2 hours. Set CLAUDE_CODE_GOAL_CHECKIN_MINUTES to change the first interval, or to 0 to turn off check-ins and automatic retries.
• Policy: /goal follows the same workspace trust rule as settings-file hooks, and it is unavailable when disableAllHooks is true or allowManagedHooksOnly is set.

How do you reuse good goal conditions?

A well-written condition is a small prompt worth keeping: the end state, the check and the constraints you learned the hard way. Kipt stores prompts as Markdown in a private GitHub repo you own, with blanks like {{test_dir:test/auth}} you fill in each time, so a goal template is a search away when you start the next migration.

Sources: Keep Claude working toward a goal, What's new, week 20 and the Claude Code changelog.