Omniscio

OmniscioGuidesClaude Code /goal

Claude Code /goal: keep working until it is done

/goal is the command that turns one prompt into a session that keeps going. You state what done looks like, and a second model checks that statement after every turn instead of leaving it to the model doing the work.

This page covers how to set a goal, how to write a condition that holds up, how the evaluation actually works, the errors that clear a goal and the ones that only pause it, and how it differs from /loop and a Stop hook.

Last checked against Anthropic's Claude Code documentation on November 20, 2026. By the Omniscio team. Updated .

What /goal does

/goal sets a completion condition, and Claude keeps working toward it without you prompting each step. Anthropic's description is precise: after each turn, a model checks whether the condition holds, and if the model judges it not yet met, Claude starts another turn instead of returning control to you.

The goal clears on its own in three situations. The condition is met. The model judges the condition impossible to satisfy. Or a turn fails on an error you have to fix. Set a goal for work with a verifiable end state; Anthropic's examples are a module migrated to a new API until every call site compiles and tests pass, a design doc implemented until its acceptance criteria hold, a large file split until each piece is under a size budget, and a labelled issue backlog worked through until the queue is empty.

It is a wrapper around a session-scoped prompt-based Stop hook, which is why it can judge a condition from the conversation without running anything itself.

Sources: the introduction and "How evaluation works" in Keep Claude working toward a goal, read November 20, 2026.

Goal, loop or Stop hook

Three things keep a session running between prompts, and they differ in what starts the next turn. Anthropic's comparison is the clearest way to choose:

  • /goal starts the next turn when the previous one finishes — or, in an interactive session, when an idle check-in or an automatic retry comes due — and stops when a model confirms the condition, judges it impossible, hits an error you must fix, or you run /goal clear.
  • /loop starts the next turn when a time interval elapses, and stops when you stop it or the loop ends on its own.
  • A Stop hook starts the next turn when the previous one finishes, and your own script or prompt decides when to stop.

/goal and a Stop hook both fire after every turn, but they are not the same tool. /goal is a session-scoped shortcut: you type a condition and it is active for the current session only. A Stop hook lives in a settings file, applies to every session in its scope, and can run a script for deterministic checks or a prompt for model-evaluated ones.

Auto mode is the frequent confusion. Auto mode approves tool calls within a single turn and does not start a new one; Claude stops when it judges the work done. /goal adds a separate evaluator that checks your condition after every turn. The two are complementary: auto mode removes per-tool prompts and /goal removes per-turn prompts. The scheduled tasks guide covers /loop and the task side.

Source: "Compare ways to keep a session running" in Keep Claude working toward a goal, read November 20, 2026.

Set a goal

One goal can be active per session, and the same command sets, checks and clears it depending on the argument. Run /goal followed by the condition.

/goal all tests in test/auth pass and the lint step is clean

Setting a goal starts a turn immediately, with the condition itself as the directive, so you do not send a separate prompt. If a goal is already active, the new one replaces it. While it runs, a ◎ /goal active indicator shows how long it has been going.

A goal does not change your permission mode. To let goal turns run unattended, run /goal in auto mode; in Manual mode Claude still asks before tool calls your settings do not already allow, such as the test command above. The permission modes guide covers the modes themselves.

While a goal is active the transcript shows each verdict the evaluator returns, and Ctrl+O shows the reason behind it. The status view also keeps the most recent reason, so you can see what Claude is working toward next.

It also runs non-interactively. claude -p "/goal CHANGELOG.md has an entry for every PR merged this week" runs the loop to completion in a single invocation. With the default text output the final response prints only when the loop ends, so a long goal looks stuck; add --output-format stream-json --verbose to see each message as it happens. Ctrl+C stops it.

Sources: "Use /goal" and "Run non-interactively" in Keep Claude working toward a goal, read November 20, 2026.

Write a condition that holds

The evaluator judges your condition against what Claude has surfaced in the conversation. It does not run commands and does not read files independently, so the condition has to be something Claude's own output can demonstrate. "All tests in test/auth pass" works because Claude runs the tests and the result appears in the transcript for the evaluator to read.

A condition that survives many turns usually has three parts, in Anthropic's words:

  • 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 test exits 0 or git status is clean.
  • Constraints that matter: anything that must not change on the way there, such as no other test file being modified.

A condition can be up to 4,000 characters. There is no default turn or time limit on the page: the bound is one you write, by putting a turn or time clause in the condition itself, such as or stop after 20 turns. Claude reports progress against that clause each turn and the evaluator judges it from the conversation.

The failure mode to avoid is a condition the evaluator cannot see. "The code is correct" is not checkable from a transcript. "The build exits 0 and no file outside src/auth changed" is.

Source: "Write an effective condition" in Keep Claude working toward a goal, read November 20, 2026.

Check the status, clear the goal

Run /goal with no arguments to see the current state. An active goal shows the condition, how long it has been running, how many turns have been evaluated, the current token spend, and the evaluator's most recent reason. The turn count and reason appear after the first evaluation has run. If no goal is active but one was achieved earlier in the session, the status shows that condition with its duration, turn count and token spend.

/goal clear removes an active goal before it resolves. Claude prints Goal cleared: and the condition, or No goal set if nothing was active. stop, off, reset, none and cancel are accepted as aliases, and /clear also removes an active goal.

A resumed session restores a goal that was still active when the session ended. That holds on every resume route: --continue, --resume with a session ID, name or transcript file path, and the session picker. Claude Code carries the condition over and resets the turn count, timer and token-spend baseline, and it does not restore a goal that was already achieved or cleared.

You can also send a message at any time to start the next turn immediately rather than waiting for the evaluator.

Sources: "Check status", "Clear a goal" and "Resume with an active goal" in Keep Claude working toward a goal, read November 20, 2026.

How the evaluation works

Each time Claude finishes a turn, Claude Code sends the condition and the conversation so far to your configured small fast model. The model returns one of three verdicts with a short reason. Not yet met means Claude keeps working and takes the reason as guidance. Met clears the goal and records an achieved entry in the transcript. Impossible clears the goal and records a failed entry with the reason, so you do not have to clear it yourself.

There is a guard against a model that talks to the evaluator without doing anything: if Claude keeps answering without tool use for several turns in a row, Claude Code stops the loop, prints a warning and returns control to you with the goal still set. Evaluation resumes after your next prompt.

Background work is treated differently. If a subagent or a background shell command is still running when a turn ends, Claude Code skips that turn's evaluation and evaluates at the end of the next turn that finishes with nothing running in the background. When the background work finishes, Claude Code delivers the result to Claude as a new turn, so you still do not have to prompt.

After background work has held the goal up for 30 minutes, a check-in is due. In it, Claude Code lists the running tasks and asks Claude to read their output, keep waiting if they are progressing, and fix or stop any that are stuck. Later check-ins wait twice as long each time, up to four times the first interval. In an interactive session Claude Code can start a turn on its own to deliver a check-in, at most three of those between your prompts.

Sources: "How evaluation works", "Background work defers evaluation" and "When a turn fails" in Keep Claude working toward a goal, read November 20, 2026.

The errors that clear a goal

When a turn fails, the goal is cleared only if the error is one you have to fix. The warning starts with Goal cleared after an unrecoverable error and ends with Run /goal again to continue. Fix the cause, then set the goal again. Anthropic's list of failures that clear it:

  • An authentication failure, when Claude Code manages its own credentials. When a host manages them, such as the desktop app or a cloud session, the goal stays active because the host restores access itself.
  • A disk too full for Claude Code to renew your claude.ai login, shown as (disk full).
  • An exhausted credit balance.
  • A context overflow that auto-compaction could not clear.
  • A model that is not available.

Every other failure leaves the goal set. On Claude Code v2.1.269 or later an interactive session also prints a line naming the cause and either retries on its own or waits: Goal still active for a failure that tends to clear itself, such as an overloaded server or a dropped connection, and Goal paused for one a retry would only repeat, such as a rate limit, a usage limit, or a hook that ended the turn. After three automatic retries the goal pauses. Setting CLAUDE_CODE_GOAL_CHECKIN_MINUTES to 0 turns off both check-ins and automatic retries.

The related errors have their own guides: login errors, rate limits and compaction errors.

Sources: "When a turn fails", "Errors you have to fix clear the goal" and "Other errors retry or pause the goal" in Keep Claude working toward a goal, read November 20, 2026.

Cost, and changing the evaluator

Evaluation tokens are billed in addition to main-turn spend, and Anthropic states that plainly. The evaluator runs on whichever provider your session is configured for and does not call tools, so the cost of a check is one read of the conversation at the small fast model's rate.

To evaluate on a different model, set ANTHROPIC_DEFAULT_HAIKU_MODEL. The warning attached to that is worth reading before you use it: Claude Code reads that variable everywhere it uses the small fast model, not only for /goal, so session title generation and other background tasks move with it too.

One requirement comes from the machinery underneath. Because the evaluator is part of the hooks system, /goal follows the same workspace trust rule as hooks in settings files. It is unavailable when disableAllHooks is true after settings precedence applies, or when allowManagedHooksOnly is set in managed settings. The hooks guide covers both switches.

Sources: "Evaluation model and cost" and "Requirements" in Keep Claude working toward a goal, read November 20, 2026.

Where these answers come from

No goal was run on this site's machine to check the page: every claim is quoted from Anthropic's documentation, and the page is a wrapper around a Stop hook whose behaviour is documented in one place.

Common questions

Can I have two goals at once?

No. One goal can be active per session, and setting a new one replaces the old one.

What happens if I send a message while a goal is running?

Your message starts the next turn immediately instead of waiting for the evaluator. The goal stays set unless it resolves.

Does a goal survive a resume?

Yes, if it was still active when the session ended. The condition is carried over and the turn count, timer and token-spend baseline reset. An achieved or cleared goal is not restored.

Does a goal keep going through a usage limit?

It pauses. A usage limit is the kind of failure a retry would only repeat, so Claude Code prints Goal paused with the cause. If your session is set to wait for the limit to reset and continue automatically, work toward the goal resumes then.