Claude Code's /goal: Set a Condition, Walk Away. A practical guide

Anthropic's Claude Code v2.1.139 introduces the /goal command, which lets developers set a completion condition for long-running tasks while a separate evaluator model judges when the condition is met, eliminating the need for per-turn prompting. The feature supports both interactive and headless modes, with conditions up to 4,000 characters that must be demonstrable through Claude's output.

Claude Code's /goal: Set a Condition, Walk Away. A practical guide Claude Code has always been turn-based: you prompt, Claude works, control returns to you. That model breaks down for long-running work — migrations, backlog grinding, "keep fixing until CI is green" — where you end up typing "continue" every few minutes. The /goal command, introduced in Claude Code v2.1.139 May 2026 , changes that. You declare a completion condition; Claude keeps starting new turns until an independent evaluator confirms the condition is met. No per-turn prompting. How it works /goal is a wrapper around a session-scoped, prompt-based Stop hook . The mechanics: - You set a condition: /goal all tests in test/auth pass and the lint step is clean . This immediately starts a turn, with the condition itself as the directive — no separate prompt needed. - When Claude finishes a turn, the condition plus the conversation so far are sent to your configured small fast model Haiku by default . - The evaluator returns a yes/no decision with a short reason. No → Claude starts another turn, with the reason injected as guidance for what to work on next. Yes → the goal clears and an "achieved" entry is recorded in the transcript. Two properties are worth internalizing: Completion is judged by a fresh model, not the one doing the work. The main model can't declare itself done; a separate evaluator decides. This avoids the classic failure mode where an agent optimistically stops early. The evaluator has no tools. It doesn't run commands or read files. It only sees what Claude has surfaced in the conversation. This directly shapes how you must write conditions more below . While a goal is active, a ◎ /goal active indicator shows elapsed time, and each evaluation's reason appears in the status view and transcript. Basic usage Set a goal starts working immediately /goal all tests in test/auth pass and the lint step is clean Check status: condition, elapsed time, turns evaluated, token spend, and the evaluator's most recent reason /goal Stop early aliases: stop, off, reset, none, cancel /goal clear Rules of the road: - One goal per session. Setting a new one replaces the active one. - The condition can be up to 4,000 characters. /clear new conversation also removes an active goal.- A goal still active when a session ends is restored on --resume / --continue , but the turn count, timer, and token-spend baseline reset. Achieved or cleared goals are not restored. Non-interactive mode /goal works in headless -p mode, the desktop app, and Remote Control. With -p , the entire loop runs to completion in a single invocation: claude -p "/goal CHANGELOG.md has an entry for every PR merged this week" Ctrl+C interrupts a non-interactive goal before the condition is met. Writing conditions that actually work Because the evaluator can only judge what's in the transcript, the condition must be demonstrable through Claude's own output . "All tests in test/auth pass" works: Claude runs the tests, the output lands in the conversation, the evaluator reads it. A condition that survives many turns has three parts: One measurable end state — a test result, a build exit code, a file count, an empty queue. A stated check — how Claude proves it: " npm test exits 0", " git status is clean". Constraints that must hold on the way there — "no other test file is modified", "public API signatures unchanged". Example of a well-formed condition: /goal every module in src/legacy/ is migrated to the v2 client API; prove it by running npm run build exits 0 and npm test all pass ; no files outside src/legacy/ and test/ are modified; or stop after 25 turns Note the last clause: there is no built-in turn or time limit. A goal runs until the condition is met or you clear it. To bound runtime, put the limit in the condition itself e.g., or stop after 20 turns — Claude reports progress against that clause each turn and the evaluator judges it from the conversation. Anti-patterns: "The code is clean and well-structured" — not measurable; the evaluator will flip-flop or never say yes. "The production deployment succeeds" — depends on state the evaluator can't verify and Claude may not be able to demonstrate safely.- Conditions with no bounding clause on open-ended work — an unachievable condition burns tokens indefinitely. When /goal makes sense and when it doesn't Good fits — substantial work with a verifiable end state: - Migrating a module to a new API until every call site compiles and tests pass - Implementing a design doc until all acceptance criteria hold - Splitting a large file into focused modules until each is under a size budget - Working through a labeled issue backlog until the queue is empty Poor fits: Single-turn tasks. If one prompt does it, a goal adds evaluator overhead for nothing. Work needing human judgment mid-flight — design decisions, ambiguous requirements. The loop won't pause to ask; it will pick something and keep going. Subjective end states. If you can't phrase completion as something a model can verify from terminal output, use normal turns. Time-driven repetition. "Re-check every 10 minutes" is /loop , not /goal see below . Work that should run without an open session — nightly tests, morning triage — belongs to scheduled tasks/cloud routines instead. /goal vs. /loop vs. Stop hooks vs. auto mode | Approach | Next turn starts when | Stops when | |---|---|---| /goal | Previous turn finishes | Evaluator model confirms condition met | /loop | A time interval elapses | You stop it, or Claude decides it's done | | Stop hook | Previous turn finishes | Your own script or prompt decides | | Auto mode | — single turn only | Claude judges the work done | /goal and a Stop hook both fire after every turn. /goal is the session-scoped shortcut; a Stop hook lives in settings, applies to every session in scope, and can run a script for deterministic checks e.g., actually executing the test suite instead of a model judgment. If you need custom or deterministic evaluation, write the hook yourself.- Auto mode is complementary, not competing: it auto-approves tool calls within a turn but never starts a new one. Auto mode removes per-tool prompts; /goal removes per-turn prompts. For fully unattended runs you typically want both. Catches Trust and hooks requirements. Because the evaluator rides the hooks system, /goal only runs in workspaces where you've accepted the trust dialog. It's unavailable when disableAllHooks is set at any settings level, or when allowManagedHooksOnly is set in managed settings — relevant in enterprise-managed environments. The command tells you why rather than failing silently. The evaluator is only as good as the transcript. If Claude claims tests pass without showing output, a lenient evaluation can end the goal prematurely; conversely, if the proof never lands in the conversation, the goal never clears. Bake the proof command into the condition. No automatic budget. Turn/time limits are your responsibility, expressed in the condition text. Unattended = your permission model applies. A multi-hour autonomous loop executes whatever your tool-approval settings allow. Review your auto-mode/permission configuration before setting a goal and walking away. Evaluator judgment is probabilistic. It's a small model making a yes/no call each turn, not a deterministic gate. For hard guarantees, a script-based Stop hook is the stricter tool. Costs Two token streams: Main-turn spend — the dominant cost. A goal is simply many consecutive turns of your main model; a 20-turn goal costs roughly what 20 manually-prompted turns would. Check /goal no argument mid-run to see cumulative token spend, and bound runs with a turns clause. Evaluation spend — one small-fast-model call per turn Haiku by default , billed on whichever provider your session uses. Per the docs, this is typically negligible compared to main-turn spend. The real cost risk isn't the evaluator — it's an unbounded or unachievable condition keeping the main model busy. Measurable end state + explicit stop clause is the mitigation. Requirements recap - Claude Code v2.1.139+ - Trusted workspace accepted trust dialog - Hooks not disabled disableAllHooks unset; no allowManagedHooksOnly restriction - Works in interactive mode, -p /headless, the desktop app, and Remote Control