Claude Code Goal Command

Claude Code works in turns. You send a prompt, Claude reads files, edits code, and runs commands, and when it thinks the work is done, it writes a summary and waits for you. On a long task, that pause often comes too early: Claude stops to ask a question, or decides it has done enough, and nothing happens until you come back and type "keep going". The Claude Code goal command removes that wait. You describe what "done" means, and Claude keeps starting new turns on its own until a separate model confirms the condition holds.

What the Claude Code goal command does

A goal is a completion condition attached to your session. Each time Claude finishes a turn, Claude Code sends the condition and the conversation so far to the small, fast model, Haiku by default. That model returns one of three verdicts, each with a short reason:

• Not yet met: Claude starts another turn right away and takes the reason as guidance for what is still missing.
• Met: the goal clears, and the transcript records it as achieved.
• Impossible: the model judges that the condition can never be satisfied, so the goal clears, and the transcript records the failure with the reason.

Why a second model? The model doing the work is the one most likely to believe it's finished. A fresh model that reads only what happened in the conversation is a stricter judge. It's also cheap: the checks run on the small model, and in our test runs they cost around a cent.

Under the hood, a goal is a prompt-based Stop hook that Claude Code sets up for you, for the current session only. One goal can be active per session, and setting a new one replaces the old one.

Write a condition that can be checked

The checking model doesn't run commands or read files. It only reads the conversation, so the condition has to be something Claude's own output can prove. "All tests pass" works, because Claude runs the tests and the result appears in the transcript. "The code is clean" doesn't, because nothing in the conversation can show it.

A condition that holds up over a long run has four parts:

• One measurable end state: every item in a backlog done, a build that succeeds, an empty issue queue.
• The check that proves it: python3 -m unittest passes, npm test exits 0, git status is clean.
• What must not change on the way there: no file in tests/ is changed. Without this part, the quickest way to make a failing test pass is to edit the test.
• A limit: "or stop after 20 turns". Claude reports its progress against the limit each turn, and the checking model judges it from the conversation like everything else.

Put together, a condition looks like this:

/goal Every item in BACKLOG.md is done: python3 -m unittest passes, no file in tests/ is changed, and README.md documents every command, or stop after 20 turns

The condition can be up to 4,000 characters, so there is room to be specific.

One thing we learned while testing it: the condition isn't a hidden test. Setting a goal starts the work with the condition itself as the instruction, so Claude sees every part of it. In our runs, the README part never sent Claude back for another turn, because Claude simply updated the README along with the rest of the work. Anything you put in the condition is something Claude will do.

Start a goal

Type /goal followed by the condition. You don't send a separate prompt, because setting the goal starts a turn immediately. Claude Code confirms with "Goal set" followed by your condition, and a "/goal active" indicator shows how long the goal has been running.

/goal must be the very first thing on the prompt line. In one of our test runs, the command was pasted from an indented block, with spaces in front of it. Claude Code sent the whole line to Claude as an ordinary prompt, Claude did the work anyway, and no goal was ever set: /goal afterwards answered "No goal set". The run looked normal, but nothing was checking it. Before you walk away, look for "Goal set".

If you planned the work first, for example in plan mode, the plan stays in the conversation, and Claude starts working toward the goal with the plan in context.

Watch a running goal

Each verdict appears in the transcript after the turn it checked. When the condition isn't met yet, you'll see a line saying so, and Claude continues on its own. Press Ctrl+O to open the transcript view and read the reason the checking model gave, and press it again to return.

Run /goal without a condition to see the status:

• The condition
• How long the goal has been running
• How many turns have been checked
• The token spend so far
• The most recent reason

The turn count and the reason appear after the first check. After the goal is met, the same command shows the achieved goal with its time, turns, and tokens. In one test run, a backlog of twelve items ended with "Goal achieved (9m · 3 turns · 42.6k tokens)".

That run had three turns only because we interrupted it twice. Claude often works through a whole backlog in one long turn, so the goal is checked once, at the end. When we stopped Claude with Esc and asked which item it was on, its answer ended a turn while the backlog was unfinished. The check returned "Goal not yet met", and Claude went back to work by itself, without anyone typing "continue". That is the goal doing its job: whenever a turn ends early, for whatever reason, the run picks up again.

If a subagent or a background command is still running when a turn ends, Claude Code skips the check for that turn and checks at the end of the next turn that finishes with nothing running in the background.

End a goal

A goal ends on its own when the condition is met or judged impossible. To stop it earlier, run /goal clear. Claude Code confirms with "Goal cleared:" followed by the condition, or "No goal set" if nothing was active. stop, off, reset, none, and cancel work as aliases for clear, and /clear, which starts a new conversation, removes the goal too.

Some errors clear the goal, because retrying won't fix them. Claude Code prints a warning that starts with "Goal cleared after an unrecoverable error" and names one of these causes:

• A failed sign-in, when Claude Code manages its own credentials. In the desktop app or a cloud session, the goal stays active, because the host restores access on its own.
• An exhausted credit balance.
• A context overflow that auto-compaction couldn't clear.
• A model that isn't available.

Fix the cause, then set the goal again with /goal and the condition.

Other errors leave the goal set. After a problem that tends to fix itself, such as an overloaded server or a dropped connection, a notice starting with "Goal still active" shows how long Claude Code waits before it retries. After three automatic retries, the goal pauses instead. After a problem that a retry would only repeat, such as an API rate limit or the usage limit of your plan, a notice starting with "Goal paused" names the cause. On a Pro plan, the usage limit is the one you are most likely to meet. If the session is set to continue when the limit resets, Claude resumes work toward the goal then. You can also send a message at any time to start the next turn.

There is one more safeguard. If Claude keeps answering the checks without making progress, with no tool use for several turns in a row, Claude Code stops the loop, prints a warning, and hands control back to you with the goal still set. And if you close a session with an active goal and resume it later, Claude Code restores the goal, with a fresh turn count, timer, and token count.

Run a goal in auto mode

A goal doesn't change your permission mode. It only decides whether Claude starts another turn. In a mode that asks before commands, Claude still stops inside a turn and waits for you to approve, for example, the test command, and the long run waits with it. For a run you want to leave alone, switch to auto mode first (Shift+Tab cycles the modes), then set the goal. Auto mode removes the prompts inside a turn, and the goal removes the prompts between turns.

Auto mode reduces prompts, but it isn't a safety guarantee, so commit your work before a long run. Git is the history you can always go back to.

A goal also works without the interactive terminal. With claude -p, the loop runs to the end in a single command:

claude -p "/goal every function in src/ has a docstring and python3 -m unittest passes"

With the default text output, only Claude's final response prints, when the loop ends, so a long goal can look stuck. Add --output-format stream-json --verbose to see each message as it happens, and press Ctrl+C to stop the run early.

Goal, loop, or Stop hook

Three tools keep a session running without you, and they differ in what starts the next turn and what ends the run:

• /goal starts the next turn when the previous one finishes, and stops when the checking model confirms the condition or judges it impossible. Use it for one piece of work with a clear end.
• /loop runs a prompt again on a time interval, for example /loop 5m check the deploy. It doesn't check a condition: it runs until you stop it or Claude decides the work is done. Use it for something you want repeated, such as watching a build.
• A Stop hook also runs after every turn, but it lives in a settings file and applies to every session in its scope. It can run a script for exact checks, or a prompt for checks a model judges. Use it for a rule you always want, and a goal for the task in front of you.

Because a goal is a hook, it follows the same rules as hooks in settings files. It isn't available in a folder you haven't trusted, when disableAllHooks is true, or when managed settings allow managed hooks only. In each case, the command tells you why instead of silently doing nothing.

Conclusion

The Claude Code goal command turns "keep going" into a condition that a separate model checks after every turn. Write the condition as something the conversation can prove: one end state, the check that proves it, what must not change, and a turn limit. Switch to auto mode, type /goal at the very start of the line, look for "Goal set", and use /goal and Ctrl+O to see where the run stands.

Relevant Training

The goal command is covered in Supervising Claude Code Agents, part of Cybrec's Claude AI training program, together with planning a long run, steering and rewinding a running agent, dynamic workflows, and agent teams.