# Claude Code Goal Command `/goal` sets a completion condition in [[Claude Code]], and Claude keeps working across turns until it holds. You stop typing "continue". After each turn, a separate small fast model reads the conversation and returns one of three verdicts: **not yet met** (Claude starts another turn and uses the reason as guidance), **met** (the goal clears and the transcript records it as achieved) or **impossible** (the goal clears and the transcript records it as failed, with the reason). It shipped in v2.1.139 on 2026-05-11, the same release that introduced [[Claude Code Agent View]]. @ClaudeDevs presented it as one of several ways Claude Code keeps Claude working "until the job is done". Why it matters: completion is decided by a fresh model, not by the one doing the work. The worker model is the one most likely to declare victory too early. That's [[Goal Engineering]] wired into the harness, and a tamer cousin of the [[Ralph Loop]], with an evaluator deciding when to stop. ## How to use it - `/goal <condition>` sets the goal and immediately starts a turn with the condition as the directive. One goal per session; a new one replaces the old. Conditions can be up to 4,000 characters. A `◎ /goal active` indicator shows how long it has been running. - `/goal` with no argument shows the condition, elapsed time, turns evaluated, token spend and the evaluator's latest reason. Ctrl+O shows the reason behind each verdict in the transcript. - `/goal clear` removes it (`stop`, `off`, `reset`, `none` and `cancel` work too). `/clear` also drops it. - It works interactively, with `-p`, in the desktop app and through [[Claude Code Remote Control]]. `claude -p "/goal CHANGELOG.md has an entry for every PR merged this week"` runs the whole loop in one invocation; add `--output-format stream-json --verbose`, or nothing prints until the end and a long run looks stuck. - Resuming a session restores an active goal (on every resume route since v2.1.239). The turn count, timer and token baseline restart from zero. - `/goal` doesn't change your permission mode. In Manual mode Claude still asks before tools your settings don't allow. Run it in [[Claude Code Auto Mode]] to go unattended: auto mode removes the per-tool prompts, `/goal` removes the per-turn ones. ## Writing a condition that works The evaluator doesn't run commands or read files. It only judges what Claude has surfaced in the conversation. So write the condition as something Claude's own output can prove: - **One measurable end state**: a test result, a build exit code, a file count, an empty queue. - **A stated check**: "`npm test` exits 0", "`git status` is clean". - **Constraints**: what must not change on the way, like "no other test file is modified". - **A bound**: "or stop after 20 turns". Claude reports progress against it each turn. Example: `/goal all tests in test/auth pass and the lint step is clean`. Good fits from the docs: migrating a module until every call site compiles and tests pass, implementing a design doc until all acceptance criteria hold, splitting a large file until each module fits a size budget, working through a labeled issue backlog until the queue is empty. ## Under the hood - `/goal` is a wrapper around a session-scoped, prompt-based `Stop` hook ([[Claude Code Hooks]]). So it needs workspace trust like other settings hooks, and it's unavailable when `disableAllHooks` is true or `allowManagedHooksOnly` is set (it tells you why instead of silently hanging). - The evaluator runs on your provider's small fast model. Evaluation tokens are billed there and are usually negligible next to the main turns. `ANTHROPIC_DEFAULT_HAIKU_MODEL` changes the evaluator model, but it also changes every other small-fast-model use (the `haiku` alias, background summarization). - If Claude keeps answering the evaluator without using tools for several turns, Claude Code stops the loop, warns you and leaves the goal set. - If a subagent or background shell is still running at the end of a turn, evaluation waits for a turn with no background work. After 30 minutes of waiting, a check-in asks Claude to review the running tasks; later check-ins back off up to 2 hours. `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` changes the first interval; `0` turns check-ins and automatic retries off. - Four failures clear the goal: an authentication failure (when Claude Code manages its own credentials), an exhausted credit balance, a context overflow auto-compaction can't fix, an unavailable model. Other errors keep it: transient ones retry up to three times, rate and usage limits pause it (v2.1.269+). ## Compared to the alternatives | Approach | Next turn starts when | Stops when | | :-- | :-- | :-- | | `/goal` | The previous turn ends (or a check-in or retry comes due) | The evaluator says met or impossible, an unrecoverable error, or `/goal clear` | | `/loop` ([[Claude Code Tasks]]) | A time interval elapses | You stop it, or Claude decides the work is done | | `Stop` hook | The previous turn ends | Your own script or prompt decides | `/goal` and a `Stop` hook both fire after every turn. The difference is scope: `/goal` is typed once and lives in the current session; a `Stop` hook lives in a settings file and applies to every session in its scope. All three keep an open session going. [[Claude Code Routines]] solve the other half of the problem: they decide when a session *starts* (schedule, API call, GitHub event), in the cloud, with nothing open on your machine. A routine is the trigger; `/goal` is the finish line. OpenAI's [[Codex CLI]] shipped its own `/goal` in v0.128.0 on 2026-04-30, with a token budget as a built-in stop condition (see [[Loop Engineering]]). ## References - Keep Claude working toward a goal (official docs): https://code.claude.com/docs/en/goal - Changelog, v2.1.139 (2026-05-11), plus v2.1.239 and v2.1.269 for resume and error handling: https://code.claude.com/docs/en/changelog - Scheduling options comparison: https://code.claude.com/docs/en/scheduled-tasks#compare-scheduling-options - Hooks reference (prompt-based hooks): https://code.claude.com/docs/en/hooks - @ClaudeDevs on X, introducing `/goal`: https://x.com/ClaudeDevs/status/2054351031279186040 - @dani_avila7 on X (2026-05-11), "Claude Code 2.1.139 added /goal": https://x.com/dani_avila7/status/2053945243582488728 - Codex CLI `/goal` (0.128.0): https://codex.danielvaughan.com/2026/05/03/codex-cli-goal-mode-persistent-objectives-token-budgets-agentic-loops/ ## Related - [[Claude Code]] - [[Claude Code Routines]] - [[Claude Code Tasks]] - [[Claude Code Hooks]] - [[Claude Code Auto Mode]] - [[Claude Code Agent View]] - [[Goal Engineering]] - [[Loop Engineering]] - [[Ralph Loop]] - [[Codex CLI]]