Goal Workflows with /goal

The /goal command (Claude Code v2.1.139+, May 2026) turns a prompt into a durable objective. You set a completion condition, Claude works on it turn after turn, and a small fast model decides after every turn whether the condition is met. The goal clears automatically the moment it is, so you can walk away from substantial work — migrations, acceptance criteria, queue drains — and come back to a finished result.

Tip

/goal is the closest thing Claude Code has to “set it and forget it”. For everything that needs a clear pass/fail end state, prefer /goal over re-prompting Claude every few turns.

When to Use /goal

Reach for /goal when you have a verifiable end state and the path between is unpredictable. Some patterns that fit:

• API migrations: “every call site of legacyAuth.verify is replaced and npm test exits 0”
• Design-doc acceptance: “all six acceptance criteria in docs/checkout-v2.md are demonstrated by passing tests”
• File-size budgets: “no file in src/components/ exceeds 400 lines and the app still builds”
• Queue draining: “every issue labelled triage-backlog has either been closed or moved to a milestone”
• Coverage targets: “test coverage for src/billing/ is at least 85% and the lint step is clean”

If the end state is fuzzy (“the code looks better”) or open-ended (“explore the codebase”), use a regular prompt or /loop instead.

How /goal Compares to Other Autonomous Workflows

Three approaches keep a session running between prompts. They differ in what starts the next turn and what stops the loop.

Approach	Next turn starts when	Stops when	Use it for
/goal	The previous turn finishes	A model confirms the condition is met	Verifiable end states with an unpredictable path
/loop	A time interval elapses	You stop it, or Claude decides the work is done	Polling external state on a cadence (CI, queues)
Stop hook	The previous turn finishes	Your own script or prompt decides	Custom evaluation logic that lives in settings.json

Auto mode is complementary: it approves tool calls within a single turn but doesn’t start a new one. Pair /goal (no per-turn prompts) with auto mode (no per-tool prompts) to get fully unattended work.

Set a Goal

Run /goal followed by the condition. The same command sets, checks, and clears the goal depending on what you pass.

/goal all tests in tests/auth pass and npm run lint exits 0

Setting a goal starts a turn immediately with the condition as the directive — you don’t send a separate prompt. A ◎ /goal active indicator shows how long it’s been running. After each turn, the evaluator returns a short reason for why the condition does or doesn’t hold, and that reason appears in the status view and transcript so you can see what Claude is working toward.

A new /goal replaces an active one. To clear early without setting a new one, use /goal clear (aliases: stop, off, reset, none, cancel).

Write an Effective Condition

The evaluator judges your condition against what Claude has surfaced in the conversation. It does not run commands or read files on its own. Conditions that hold up over many turns share three traits:

• 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 — npm test exits 0, git status is clean, wc -l on a file is below a number.
• Constraints that matter: anything that must stay true — no other test file is modified, no changes to package.json, no new dependencies.

Conditions can be up to 4,000 characters. To bound how long a goal runs, include a turn or time clause:

/goal every TODO in src/billing/ resolved or stop after 25 turns

Claude reports progress against that clause each turn and the evaluator judges it from the conversation.

Don't write conditions Claude can't prove

“The code is more readable” or “performance is better” are unverifiable from the transcript alone. Translate them into something concrete: “every file in src/utils/ is under 200 lines” or “the benchmark in bench/redirect.bench.ts reports ≥ 30% improvement over the baseline committed in bench/baseline.json”.

Check Status

Run /goal with no arguments to see the current state:

/goal

If a goal is active, the status shows the condition, how long it’s been running, how many turns have been evaluated, current token spend, and the evaluator’s most recent reason. If no goal is active but one was achieved earlier in the session, the status shows the achieved condition along with its duration, turn count, and token spend.

Clear a Goal

Use /goal clear to remove an active goal before its condition is met. Running /clear to start a new conversation also removes the active goal.

Resume with an Active Goal

A goal that was still active when a session ended is restored when you --resume or --continue that session. The condition carries over; the turn count, timer, and token-spend baseline reset on resume. A goal that was already achieved or cleared is not restored.

Run Non-Interactively

/goal works in non-interactive mode (-p) and through Remote Control. Setting a goal with -p runs the loop to completion in a single invocation:

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

Interrupt with Ctrl+C to stop a non-interactive goal before its condition is met. This pattern is useful for nightly cron jobs and CI runners — pair it with -p, an auto-mode profile, and a tight condition for fully hands-off work.

How Evaluation Works

/goal is a wrapper around a session-scoped prompt-based Stop hook. Each time Claude finishes a turn, the condition and the conversation so far are sent to your small fast model (default: Haiku). The model returns yes-or-no plus a short reason:

• No → Claude keeps working; the reason becomes guidance for the next turn.
• Yes → The goal clears and an “achieved” entry is recorded in the transcript.

The evaluator runs on whichever provider your session is configured for. It doesn’t call tools, so it can only judge what Claude has surfaced. Evaluation tokens bill on the small fast model — typically negligible compared to main-turn spend.

Requirements

/goal runs only in workspaces where you have accepted the trust dialog, because the evaluator is part of the hooks system. The command is unavailable when:

• disableAllHooks is set at any settings level
• allowManagedHooksOnly is set in managed settings

In each case, /goal tells you why instead of silently failing.

Patterns That Work

Migrations

/goal every import of '@old-pkg/auth' is replaced with '@new-pkg/auth',
the project compiles via `tsc --noEmit`, and `npm test` exits 0.
Do not edit package.json or lockfiles.

Combine with auto mode to let Claude apply edits, run the compiler, and rerun tests until everything is green.

Acceptance criteria

/goal each of the six acceptance criteria in docs/checkout-v2.md
is demonstrated by a passing test in tests/checkout-v2/.
Stop after 30 turns and summarize remaining gaps.

The turn cap turns an open-ended goal into a bounded one — if the evaluator hasn’t said yes after 30 turns, you get a partial report rather than runaway spend.

Backlog triage

/goal every issue labeled 'triage-needs-repro' in the current repo
has either a confirmed reproduction step in its body or has been
closed with a comment explaining why.

Pair with a GitHub MCP server so Claude can read and update issues directly.

Size budgets

/goal no file in src/components/ exceeds 350 lines and `npm run build`
exits 0. Do not move logic to new files outside src/components/.

The constraint clause prevents the “split this into 12 files in src/utils/” escape hatch.

Related Workflows

Agent view: dispatch goals in parallel Run several /goal sessions side by side and check on them when the row shows complete.

Slash commands reference Every built-in command, keyboard shortcut, and session-management pattern.

Hooks automation Build your own prompt-based Stop hook when you need custom evaluation logic.

Multi-file workflows When to use /goal vs subagents vs agent teams for parallel work.