Let Claude run until it is done with /goal

Most sessions go prompt, answer, prompt, answer. For a job with a clear finish line, like getting a test folder green, that rhythm wastes your time. This guide shows you how to hand Claude a finish line with /goal and let it keep going until a separate model confirms it got there.

What you will have at the end

A /goal condition you wrote yourself that Claude can prove it met.
A turn bound so a goal can never run forever.
A setup where goal turns run without you approving every tool call.
The commands to check, stop and resume a goal.

Before you start

Claude Code installed, signed in, and opened in a project with tests or a build step.
A task with a clear end state. Good examples from the docs: migrate a module until every call site compiles and tests pass, or work through a labelled issue backlog until the queue is empty (goal docs).
Run claude --version so you know which version you are on (costs page). Some behaviour below names the version it needs.

Step 1: try the smallest goal

Type this in a session, changing the folder to one in your project:

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

Setting a goal starts a turn straight away, using the condition as the instruction, so you do not send a separate prompt (goal docs). A ◎ /goal active indicator shows how long it has been running.

Here is what happens next. After every turn, Claude Code sends your condition and the conversation so far to a small fast model, the evaluator. It returns one of three verdicts: not yet met, met, or impossible (how evaluation works). Not yet met means Claude starts another turn, using the evaluator's reason as guidance. Met or impossible clears the goal.

The useful part is that a fresh model decides when the work is done, not the one doing the work.

Step 2: write a condition the evaluator can check

The evaluator does not run commands or read files. It only judges what Claude has already shown in the conversation (write an effective condition). So write the condition as something Claude's own output can prove.

A strong condition has three parts, per the docs:

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

Compare these two:

/goal make the auth module better

/goal npm test exits 0 for test/auth, run it and show the summary line; do not modify any file outside src/auth and test/auth

The first gives the evaluator nothing to judge. The second names the command, the proof and the boundary. The condition can be up to 4,000 characters, so you have room to be precise (goal docs).

Step 3: add a turn bound

Always give a goal a way to stop. Add a turn or time clause to the condition, and Claude reports progress against it each turn while the evaluator judges it from the conversation (goal docs):

/goal npm test exits 0 for test/auth and the summary line is shown, or stop after 20 turns

Pick a bound that matches the job. A small fix might need 10 turns. A migration across many files might need 40. If it hits the bound, you have a clear point to read what happened and adjust.

There is also a safety net built in. If Claude keeps answering the evaluator without using any tools for several turns in a row, Claude Code stops the loop, warns you and hands control back with the goal still set (how evaluation works).

Step 4: let it run unattended with auto mode

A goal does not change your permission mode (goal docs). In Manual mode, Claude still stops and asks before tool calls your settings do not already allow, like running the test command. That defeats the point of walking away.

Auto mode fixes this. In auto mode, a classifier model reviews actions instead of you (permission modes). The goal docs sum up how they fit together: "auto mode removes per-tool prompts, and /goal removes per-turn prompts" (goal docs).

To switch during a session, press Shift+Tab until the status bar shows ⏵⏵ auto mode on. To start in auto mode (permission modes):

claude --permission-mode auto

From Claude Code v2.1.283, auto mode is already the starting mode for interactive terminal and VS Code sessions, so you may not need to do anything (permission modes). It needs a supported model, and your organisation can turn it off.

Step 5: check, stop and resume

Three commands cover the rest (use /goal):

/goal

With no argument, this shows the condition, how long it has run, how many turns have been evaluated, the current token spend and the evaluator's latest reason.

/goal clear

This removes an active goal. Claude prints Goal cleared: followed by the condition. Running /clear for a new conversation also removes the goal. Only one goal can be active per session, and setting a new one replaces the old one.

If you close a session with a goal still running, resuming it with --continue or --resume restores the goal, with the turn count, timer and token baseline reset (resume).

You can also run a goal from a script. With -p, the whole loop runs in one call (run non-interactively):

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

Add --output-format stream-json --verbose to see each message as it runs, otherwise it can look stuck until the end.

Current numbers (checked 2026-11-06)

Condition length: up to 4,000 characters (goal docs).

First check-in while background work holds a goal: after 30 minutes, then less often (background work).

Idle check-ins: at most three per goal between your prompts (background work).

Automatic retries after a passing failure: three, then the goal pauses (when a turn fails).

Check it worked

While the goal runs, the transcript shows each verdict, and Ctrl+O shows the reason behind it (goal docs). When the evaluator judges the condition met, Claude Code clears the goal and records an achieved entry in the transcript. Run /goal again: with no active goal, it shows the achieved condition with its duration, turn count and token spend (check status).

Then check the work yourself. Run the same test command the condition named and confirm the result matches.

Common problems

The goal never ends. The condition is probably vague, so the evaluator keeps saying not yet. Clear it with /goal clear and rewrite it with a command, a proof and a turn bound.

Claude keeps stopping to ask permission. You are in Manual mode. Switch to auto mode with Shift+Tab, or add allow rules for the commands the goal needs (permission modes).

The goal cleared with a warning. A warning that starts Goal cleared after an unrecoverable error means something you must fix, such as a sign-in failure, an exhausted credit balance, a context overflow or an unavailable model. Fix it and set the goal again (when a turn fails).

Usage climbs while you are away. If background work keeps a goal waiting, Claude Code checks in on it even when the session is idle, and each check-in sends your full context (costs page). Setting CLAUDE_CODE_GOAL_CHECKIN_MINUTES to 0 turns check-ins and automatic retries off (goal docs).

/goal says it is unavailable. It follows the same workspace trust rule as hooks, and it is off when disableAllHooks is true or managed settings set allowManagedHooksOnly (requirements). The command tells you which.

Explore, plan, code, verify: the loop that works: how to plan the work before you hand it to a goal.
From idea to launched product in a weekend: SPEC and PLAN templates with ready /goal prompts.

Sources

Last checked: 2026-11-06