Claude Code's /goal is a command where you write down one condition for "when is this done," and Claude keeps working on its own until it reaches that point. Each time a turn (one response from Claude) ends, a small separate model checks whether the condition has been met. If it hasn't, Claude is sent on to the next step. This article organizes how to use it and when it stops, based on the official documentation (as checked on October 24, 2026). It also reports the results of trying it on real work on this site, including token usage and a check on the quality of the finished output.
What it does
Keeps going until the end condition is met
Write something like /goal all tests pass and work starts right away. It continues until the condition is met, the evaluator judges it cannot be met, or an error that needs fixing appears.
How it judges
A separate model checks each time
The evaluator reads only the results that appear in the conversation. It does not look at files or run commands itself, so the condition should be something Claude's output can prove.
What we found in testing
For a single-turn task, the extra cost is one evaluation
For a mechanical task, even 321 items finished in one turn, so the added cost was one evaluation. The evaluator did not catch small unnatural details in the finished writing.
Table of contents
- 1. What /goal is: difference from a normal request, /loop, and Stop hooks
- 2. How to use it: setting, checking status, clearing
- 3. How judging works and when it stops
- 4. How to write a condition
- 5. Results of two /goal trials (compared with one normal request)
- 6. What we learned: suited and unsuited tasks
- 7. Differences from Codex /goal
- Summary
- FAQ
1. What /goal is: difference from a normal request, /loop, and Stop hooks
When you ask for work normally, Claude stops once it decides the work is finished and waits for your next instruction. When you set a /goal, a check runs at the end of each turn (one response from Claude). If the condition is not yet met, the next turn starts even if you send nothing. The official documentation gives the following kinds of larger tasks, where the end state can be checked, as good examples:
- Move a module to a new API, until every call site compiles and the tests pass
- Implement a design document, until all acceptance criteria are met
- Split large files, until every file is at or below a set size
- Work through a list of labeled issues until the list is empty
There are three similar mechanisms. The official documentation explains that you should choose among them based on "what starts the next turn."
| Mechanism | When the next turn starts | When it stops |
|---|---|---|
/goal | When the previous turn ends (during an interactive session, also through periodic checks or automatic retries) | When the evaluator judges the condition met or unmeetable, when an error needs fixing, or when you run /goal clear |
/loop | When a set amount of time has passed | When you stop it, or when Claude decides the work is finished |
| Stop hook | When the previous turn ends | When a script or prompt you wrote makes the decision |
In essence, /goal is a "Stop hook that judges with a prompt," and it works only within that conversation. A Stop hook is written in a settings file and applies to all conversations. /goal is written on the spot and applies only to that conversation.
The permission mode does not change. If you want turns to keep running without confirmation, switch to auto mode in permission modes and then use /goal. If you stay in a manual mode, you will be stopped for confirmation each time an operation you have not approved comes up. The official documentation says that auto mode reduces confirmations within a single turn, while /goal reduces per-turn instructions, and that the two can be combined.
Source: Keep Claude working toward a goal (Claude Code official documentation, confirmed October 24, 2026).
2. How to use it: setting, checking status, clearing
A conversation can hold only one goal. The same /goal command handles setting, checking, and clearing, depending on what follows it.
- Set a goal: type
/goalfollowed by the condition Example:/goal the tests in test/auth all pass and lint is clean too. Setting it starts a turn immediately, and the condition itself serves as the instruction, so you don't need to send a separate request. If a goal already exists, the new condition replaces it. Conditions can be up to 4,000 characters. - Check status: type
/goalalone It shows the condition, the elapsed time, the number of evaluations, the tokens used, and the reason for the most recent evaluation. The count and reason appear after the first evaluation. - Stop:
/goal clearThis removes the goal before any evaluation occurs.stop,off,reset,none, andcancelhave the same effect. Starting a fresh conversation with/clearalso removes the goal.
If you resume a conversation, a goal that had not yet finished comes back. The condition carries over, but the counts for turns, time, and tokens start over. It works in the desktop app, in remote sessions, and with automated runs via claude -p. claude -p "/goal …" keeps running in a single execution until the goal is finished, so if you want to watch progress, add --output-format stream-json --verbose.
Caution when pasting a condition in the desktop app. If you paste "/goal plus a multi-line condition" all at once, the entire text may be sent as ordinary pasted text, and /goal may not work as a command (confirmed on October 23, 2026, on the Windows desktop app with Claude Code 2.1.308). In the input field, /goal appears highlighted, so you cannot tell the difference by looking. To be sure, type /goal by hand, select it from the suggestions, and then paste the condition. Check that it took effect by looking for a line starting with "Goal set:" just below.
3. How judging works and when it stops
Each time a turn ends, Claude Code sends the condition and the conversation so far to a "small, fast model." The judgment has three outcomes, each with a short reason. In this site's environment, the evaluator was Claude Haiku 5.5 (confirmed from the conversation records).
The evaluator uses no tools, and it judges only from what appears in the conversation. It does not reread files or run tests itself. If Claude answers the evaluator without using any tools for several turns in a row, Claude Code stops the loop, shows a warning, and returns control to you with the goal still in place.
When it stops because of an error
| What happened | Goal | What happens |
|---|---|---|
| An error you need to fix (login failure, a depleted credit balance, context overflow that automatic summarization cannot resolve, an unavailable model) | Cleared | Fix the cause and set /goal again |
| Login failure in a desktop app or cloud session | Kept | The app itself handles the login again |
| A failure that usually clears up on its own (server congestion, dropped connection) | Kept | It waits and retries automatically. After three retries, it pauses (during interactive use in version 2.1.269 and later) |
| A failure that will recur on retry (API usage limit, claude.ai usage cap, a hook stopping the turn) | Kept | It pauses. If the setting waits for the usage cap to reset, it resumes from where it stopped once the cap resets |
When subagents or background work are running
If a subagent or background command is still running at the end of a turn, judgment for that turn is deferred. When the results come back, they reach Claude as a new turn. If 30 minutes pass while waiting, a "mid-check" runs. It reads the output of the running work and, if progress is being made, waits. If the work has stalled, it prompts Claude to fix the problem or stop. By default, the interval doubles at 30 minutes, 1 hour, and 2 hours, and after that it repeats every 2 hours. You can change the first interval with the environment variable CLAUDE_CODE_GOAL_CHECKIN_MINUTES. Setting it to 0 stops both the mid-checks and the automatic retries.
When it cannot be used, and cost
The evaluator is part of the hook mechanism, so, as with hooks, it cannot be used in folders you have not marked as trusted. It also cannot be used when disableAllHooks is set to true in settings, or when allowManagedHooksOnly is enabled in administrator settings. In those cases, the reason is displayed. The tokens used for judging are billed at the rate for the small, fast model. The official documentation says this is usually "very small compared with the main work." You can change the evaluator model with ANTHROPIC_DEFAULT_HAIKU_MODEL, but this setting also affects other processes that use the small model, such as conversation summarization.
Source: Keep Claude working toward a goal (confirmed October 24, 2026).
4. How to write a condition
The evaluator reads only the conversation, so write the condition so that Claude's own output can prove it. The official documentation lists three elements of a condition that hold up well over long runs.
npm test finishes with success" or "git status is clean."If you want to put a limit on how long it runs, write it into the condition, for example "or stop after 20 turns." The official documentation has no dedicated setting like the token budget in Codex /goal.
| How it is written | How the evaluator sees it |
|---|---|
| Improve the quality and keep going until it's done | There is no way to decide what "done" means |
| Fix it until all the tests pass | It can be judged if the results appear in the conversation, but which tests is unclear |
npm test finishes with success, and its output is shown in the conversation (do not change src/legacy, stop after 30 turns) | The end state, the way to check it, what must be kept, and the limit are all specified |
One caution we learned from testing on this site: write what you want kept in the condition itself, not in a separate instruction file. The evaluator judges literally from the condition, so an instruction placed in a different file can count as "met" even if it was not followed. This actually happened in this site's experiment (see Chapter 5).
5. Results of two /goal trials (compared with one normal request)
We used /goal for a task on this site's articles: aligning the sentence-ending periods. In the Japanese articles, there were 1,035 places in existing articles where the closing "。" was either present or missing (counted by this site's checking script for sentence-ending periods). Because the rule for fixing them was set and the end state was clearly "0 items in the check," we chose it as a task suited to /goal. We ran /goal twice with different scopes and, for reference, placed one normal request beside them.
The reference run was one where we pasted the condition all at once while trying /goal, and as described in the caution in Chapter 2, it did not work as a command and ran as a normal request. We list it in the table as a reference value for the same kind of task requested normally (the scope and counts differ, so this is not a strict comparison). For the two /goal runs, we typed /goal by hand, selected it, and confirmed the "Goal set:" line. The runs took place on October 23, 2026, on the Windows desktop app with Claude Code 2.1.308, with Claude Opus 5.5 as the worker model and auto as the permission mode.
| Comparison | Reference: normal request | /goal (smaller) | /goal (larger) |
|---|---|---|---|
| Scope and count | 10 articles, 166 items | 9 articles, 119 items | 48 articles, 321 items |
| Time taken | 6 min 9 sec | 5 min 54 sec | 10 min 7 sec |
| Turns | Finished in 1 turn | Met in 1 turn | Met in 1 turn |
| Evaluations, time | None | 1, 5.6 sec | 1, 9.0 sec |
| Worker output tokens | 15,254 | 14,750 | 27,835 |
| Evaluator tokens | None | Output 899, cache write 64,299 | Output 1,569, cache write 114,410 |
| Equivalent cost recorded by Claude Code | $1.33 | $1.26 | $2.74 |
| Items a person fixed after checking | None | None | Two unnatural sentences |
The figures were totaled from the records of each conversation (the JSONL files that Claude Code saves). The equivalent cost is what Claude Code calculated and recorded at API rates. It is not billed for subscription use. Each result is from a single run, and the scope and counts differ from run to run. The figures would change with a different kind of task or model. Evaluator cache writes correspond to the amount of conversation loaded for judging. The equivalent cost is the total for the worker and the evaluator.
The conditions we actually wrote
These are the conditions written after /goal in the two runs. Names specific to this site (the checking script, the working notes file, and the tools that update records) were replaced with wording that says what they do. The detailed steps of the work (the precedents for fixing, and the files not to touch) were written in a working notes file (a Markdown file), and the condition pointed to that file.
# Smaller run
For the Japanese text of articles 200 to 209 (9 articles), the sentence-ending checking script reports 0 items (show each of the 9 articles' check results in the conversation), and commit and push are completed following the steps in the working notes. Stop after 30 turns.# Larger run
For the Japanese text of articles 100 to 199, the sentence-ending checking script reports 0 items. Keep: follow the steps in the working notes (fix only the punctuation, following the decided precedents; do not change words, meaning, translations, metadata, or tools). At the end of every turn, write one line stating "remaining ○ items (○ articles)." At the end, show in the conversation the check results for all 48 articles in scope, the list of changed files (only the text and the consistency records), a passing tag check, and the result of updating the consistency records, then complete commit and push by path. Do not deploy. Stop after 40 turns.git diff --stat), the tag check, and the record updates be shown in the conversation.In the smaller run, "write the remaining count every turn" was written only in the working notes. Claude finished without writing it, and the evaluator judged the goal "met," noting in its reason that "the instruction in the procedure was not followed, but the condition does not require it." We reflected this lesson (Chapter 4) in the condition for the larger run.
Checking the finished output
We did not take the evaluator's "met" at face value. Each time, we checked the diffs line by line in a separate conversation and reran the checks.
/goal runs confirmed 0 items with the corrected tool. The evaluator's "met" depends on the checking tool being correct.6. What we learned: suited and unsuited tasks
Mechanical tasks finish in one turn
Every run finished its work in one turn. Within one turn, Claude can use tools dozens of times (the larger run used Bash 32 times), so a task that a script can handle finishes in one go even with 321 items. For this reason, the main advantage of /goal, "if more is needed, continue in the next turn," never came into play for this kind of work. The results come from one run per scope, but between the normal-request reference and the two /goal runs, we saw no large difference in time or finished quality. The added cost was one evaluation per run, and each evaluation took 5.6 seconds and 9.0 seconds (the whole work took about 6 minutes and about 10 minutes).
The evaluator reads the whole conversation
In the larger run, the evaluator read 114,410 tokens, which was the entire work conversation passed on as it was. The longer the conversation, the heavier each evaluation. For work that runs many turns, or for starting /goal in the middle of an already long conversation, the cost of evaluation is likely to be greater than in this run.
The evaluator checks whether the condition is met
The evaluator accurately checked items in the condition, such as the check results and whether a commit existed. On the other hand, it does not check qualities that do not show up in numbers, such as whether a sentence reads naturally. "Met" means that what was written in the condition appeared in the conversation. It does not replace checking the finished output.
This experiment tested only "work that finishes in one turn." Below, we separate the official documentation's examples from the author's own view of suitable tasks.
7. Differences from Codex /goal
OpenAI's Codex also has a /goal command with the same name. The concept (keep working while holding to an end condition) is the same, but the operations and the way limits are set differ. For detailed instructions on Codex, see How to use Codex /goal.
| Comparison | Claude Code | Codex |
|---|---|---|
| Operations | Set, check status, and clear (/goal clear). To change it, set a new condition | View, edit, pause, resume, and clear (/goal edit, pause, resume, clear) |
| Who judges | A separate small, fast model reads the conversation at the end of each turn | Codex repeats work and checks (there is no description that a separate model judges) |
| Limits | No dedicated setting. Write something like "stop after 20 turns" into the condition | There is a token budget per goal |
| When it stops automatically | The condition is judged met or unmeetable, or an error needing a fix appears (paused on usage limits or usage caps) | The condition is met, the budget is reached, or your judgment is required (cannot continue because of an account usage limit) |
Sources: for Claude Code, Keep Claude working toward a goal; for Codex, Using Goals in Codex (OpenAI Cookbook) and this site's "How to use Codex /goal." Both current as of October 24, 2026.
Summary
/goalis a command where you write one condition for the end, and a separate model judges it at the end of each turn, keeping Claude working until the condition is met. The same command handles setting, checking status, and clearing.- The evaluator reads only the conversation. Write the condition so that its end state, how to check it, and what must be kept can be proven by Claude's output, and include the limit in it as well.
- The permission mode does not change, so if you want to hand off the work, combine
/goalwith auto. - In this site's experiment, a mechanical task finished in one turn even with 321 items. For this single-turn task, the added cost was one evaluation. In the author's view, the benefit appears in work that cannot finish in one turn.
- "Met" means that what was written in the condition appeared in the conversation. Check finished quality, such as the naturalness of sentences, separately.
- When you paste an entire condition in the desktop app, it may not work as a command. Confirm with the "Goal set:" line.
Steps to get started: Switch to auto mode → write the condition in the form of Chapter 4 (end state, how to check it, what must be kept, limit) → type /goal by hand, paste the condition, and confirm "Goal set:" → after it reports "met," read the diffs yourself.
FAQ
Q. Does using /goal increase the cost?
Yes, by the amount of the evaluations. Evaluations are run by a small, fast model, and the official documentation says the cost is "usually very small." In this site's experiment, the work that finished in one turn had one evaluation, and it took a few seconds. However, because the evaluator reads the whole conversation, the longer the conversation, the heavier each evaluation.
Q. How do I stop it partway through?
Remove the goal with /goal clear. stop and cancel work the same way. If you are running it with claude -p, stop it with Ctrl+C. Clearing the goal does not undo the changes made so far.
Q. Can the evaluator say "not yet" even when Claude says it is finished?
Yes. That is why a separate model does the judging. If the evaluator says "not yet," the next turn starts using its reason as a clue. Conversely, once results that meet the condition appear in the conversation, the goal is "met," so quality you did not write into the condition is not guaranteed.
Q. How many turns will it run before stopping?
There is no fixed limit. It stops when the condition is met, when it is judged unmeetable, when an error needing a fix appears, or when you clear it. If you want a limit, write it into the condition, for example "or stop after 20 turns." The evaluator reads only the conversation, so it helps to include something like "at the end of every turn, state the number of turns elapsed" in the condition. (None of the runs in this experiment ended in one turn, so we did not test stopping at a limit.)
Q. Should I use /loop or /goal?
Use /goal when the end state is defined. Use /loop when you want to check the same thing at set intervals. For example, "check every 5 minutes until the deployment finishes" suits /loop, and "fix until all tests pass" suits /goal.
References: Keep Claude working toward a goal, Run prompts on a schedule, and Hooks guide (Claude Code official documentation); Using Goals in Codex (OpenAI Cookbook). Confirmed October 24, 2026.
