Keep Claude Code working toward a goal with /goal

/goal sets a finish line. After every turn, a second model checks whether the condition is true; if not, Claude starts another turn instead of handing control back to you. The goal clears when the condition is met, when the checker judges it impossible, or when an error you have to fix stops the turn. Here is how to use it without losing control of the clock or the bill.

When it fits

Substantial work with an end state you can verify: migrating a module until every call site compiles and the tests pass, implementing a design doc until each acceptance criterion holds, splitting a big file until each part is under a size limit, or working through a labeled backlog until the queue is empty. For vague or open-ended work, use a normal conversation.

/goal, /loop or a Stop hook?

• /goal: the next turn starts when the last one finishes. It stops when the checker says the condition is met or impossible, when a turn fails on an error you have to fix, or when you clear it.
• /loop: the next turn starts when a time interval passes. It stops when you stop it or Claude decides the work is done. See scheduling with /loop.
• Stop hook: fires after every turn like /goal, but lives in your settings file, applies to every session in its scope, and can run your own script or prompt as the check.

As we read the docs, /goal is a shortcut for a session-scoped, prompt-based Stop hook. It also pairs with auto mode: auto mode removes the per-tool prompts, /goal removes the per-turn prompts. A goal does not change your permission mode, so in manual mode Claude still asks before anything your settings don't already allow.

Set one

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

Setting a goal starts a turn right away, with the condition as the instruction. One goal can be active per session; a new one replaces the old. A /goal active indicator shows how long it has been running, and you can press Ctrl+O to see the reason behind each verdict.

Write a condition the checker can verify

The checker only judges what Claude has put in the conversation. It does not run commands or open files itself. So write the condition as 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. A good condition usually has:

• One measurable end state: a test result, a build exit code, a file count, an empty queue.
• A stated check: "npm test exits 0", "git status is clean".
• Constraints that matter: "no other test file is modified".

It can be up to 4,000 characters. To bound how long it runs, put a limit in the condition itself, such as or stop after 20 turns; Claude reports progress against it each turn.

Status, clear, resume

• /goal alone shows the condition, how long it has run, turns evaluated, token spend so far and the checker's latest reason.
• /goal clear removes it. stop, off, reset, none and cancel work too, and /clear removes any active goal.
• Resuming a session restores a goal that was still active. The condition carries over; the turn count, timer and token baseline start again. An achieved or cleared goal is not restored.

Without a screen

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

With -p the whole loop runs in one call. With the default text output you only see the final answer, so a long goal can look stuck; add --output-format stream-json --verbose to see each message as it happens. Ctrl+C stops it. More on non-interactive runs in running Claude Code from a script.

How the check works, and what it costs

When Claude finishes a turn, Claude Code sends the condition and the conversation so far to your small, fast model, which answers not yet met (Claude continues, using the reason as guidance), met (the goal clears) or impossible (it clears with the reason recorded). If Claude keeps answering the checker without using any tool for several turns, Claude Code stops the loop and gives control back with the goal still set. The docs say the checker's tokens are billed on the small model and are typically small next to the main turns, so the real cost is the turns themselves; that is why a turn limit in the condition matters. One warning from the docs: ANTHROPIC_DEFAULT_HAIKU_MODEL, which changes the checker's model, also changes the model used for the haiku alias, session titles and some other background tasks.

What clears or pauses a goal

• Errors you have to fix clear it: a sign-in failure (when Claude Code manages its own credentials), an exhausted credit balance, a context overflow that auto-compaction couldn't clear, or an unavailable model. Fix the cause and run /goal again.
• Other errors keep it set. Ones that tend to clear alone, like an overloaded server or a dropped connection, are retried (after three tries it pauses). Ones a retry would only repeat, like a rate limit, a usage limit or a hook that ended the turn, pause it with a notice. Send any message to restart at once.
• Background work delays the check: if a subagent or a background command is still running when a turn ends, that turn isn't evaluated. After about 30 minutes of waiting, Claude Code does a check-in: it lists what is running and asks Claude to read the output, keep waiting or stop stuck tasks.

Requirements

/goal is part of the hooks system, so it follows the same workspace-trust rule as hooks in settings files. It is unavailable when disableAllHooks is true or when managed settings allow only managed hooks; the command says why instead of doing nothing.

All the guides are in the guides index. For the hooks behind it, see the hooks guide. This follows Anthropic's /goal documentation as we read it in October 2026. We are not affiliated with Anthropic. We wrote this from the documentation and have not tested every case. Details such as retries, check-ins and requirements depend on your version, and where this page and the documentation disagree, the documentation wins.

The free loop-stop skill gives long tasks a limit and a stop rule, which is the same idea as the turn limit above. If you want a second pair of eyes on your CLAUDE.md and settings, the Tune-Up Kit is a checklist for exactly that.