How to Use /goal in Claude Code for Multi-Turn Tasks

Claude Code's /goal command keeps the current session working across multiple turns until an evaluator decides that a stated completion condition has been met. It is useful for work such as clearing a test failure backlog or completing a migration—not for vague requests with no objective stopping point.

Requirement: /goal requires Claude Code 2.1.139 or later. It does not grant additional permissions, and only one goal can be active in a session.

Set a goal

Enter /goal followed by a condition that Claude can prove from its work:

/goal all tests in test/auth pass, npm run lint exits 0, and no test files are modified

Setting the goal starts a turn immediately; a separate task prompt is not required. After each turn, a small evaluator model reads the conversation and decides whether the condition is satisfied. If the answer is no, Claude begins another turn and receives the evaluator's reason as guidance. If the answer is yes, the goal is cleared and recorded as achieved.

Write a condition the evaluator can verify

The evaluator does not independently run commands or inspect files. It can only assess evidence that Claude has surfaced in the conversation. A reliable condition therefore includes:

• An observable end state: for example, a passing test suite, successful build, required file count, or empty issue queue.
• A verification method: name the command or check whose output demonstrates completion.
• Important boundaries: state files that must not change, compatibility requirements, or other constraints.
• A stopping limit: for uncertain work, add a clause such as “or stop after 15 turns and report the blocker.”

A weak condition such as /goal make the app better gives the evaluator no objective finish line. A stronger version is:

/goal npm test and npm run build both exit 0, the health endpoint returns HTTP 200, and files under config/ are unchanged; stop after 12 turns if blocked

A goal condition can contain up to 4,000 characters, but concise acceptance criteria are easier to inspect.

Check, replace, or clear a goal

• Run /goal with no argument to see the active condition, elapsed time, evaluated turn count, token spend, and latest evaluator reason.
• Enter /goal with a new condition to replace the current one.
• Run /goal clear to cancel it. stop, off, reset, none, and cancel are also accepted in place of clear.

An active goal is restored when you resume its session with --resume or --continue. A goal that was achieved or cleared is not restored.

Permissions and unattended use

/goal continues the session between turns, but it does not approve tool calls. In the default permission mode, Claude can still pause to ask before running a command or taking another action that is not already allowed. Pair the goal with Claude Code's auto mode only when you understand and accept the actions it may approve in the current workspace.

This distinction matters:

• Auto mode removes eligible tool-approval pauses within a turn.
• /goal starts another turn when the evaluator says the condition is not yet met.

Keep source control available, define a narrow scope, and review the resulting diff. Do not give an unattended goal unnecessary access to production credentials, deployments, or destructive commands.

Run /goal non-interactively

Use Claude Code's -p flag and place the goal command in the prompt:

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

With the default text format, a long-running goal may print nothing until it finishes. To stream messages as the loop runs, use:

claude -p "/goal npm test exits 0 and npm run lint exits 0" --output-format stream-json --verbose

Press Ctrl+C to interrupt a non-interactive run. The command is claude; old examples using claude-code --headless --goal do not match the current CLI syntax.

When to use /goal, /loop, or a Stop hook

• Use /goal when the next turn should begin as soon as the current turn finishes and an evaluator says a measurable condition is still false.
• Use /loop when work should repeat after a time interval.
• Use a Stop hook when you need a reusable, settings-based check or a deterministic script instead of a session-only model evaluation.

The command is implemented as a session-scoped prompt-based Stop hook. It is unavailable when all hooks are disabled, when managed settings permit only managed hooks, or before the workspace trust dialog has been accepted.

A practical goal checklist

1. Update Claude Code to version 2.1.139 or later.
2. Commit or stash unrelated changes so the resulting diff is easy to review.
3. State one measurable outcome, the command that proves it, and files that must remain unchanged.
4. Add a turn limit when external access or an unknown failure could block completion.
5. Monitor the ◎ /goal active indicator and use bare /goal to inspect progress.
6. After completion, review the diff and rerun the named checks yourself before merging or deploying.

For the current syntax and restrictions, see the official Claude Code /goal documentation.