The /goal Command: Goal-Directed Autonomous Runs

The /goal command gives a coding agent an objective with a verifiable finish line and keeps it working turn after turn until the objective holds, a budget or limit stops it, or you clear it. Claude Code, Codex and Cursor all ship /goal, but they differ on who decides the work is done, and that difference decides how far you can trust the result.

This page is for developers who run long agent sessions and for tech leads who want those runs to end in evidence. You are three hours into a migration. The agent finishes a turn, you skim the diff and type “keep going”, and it finishes another turn. The finish line is obvious (“every call site migrated, all tests green”), yet every step waits on you pressing Enter.

What you’ll walk away with from /goal

• A side-by-side view of how /goal works in Claude Code, Codex and Cursor, and who judges “done” in each
• The commands to start, inspect, pause and clear a goal run in each tool
• Three copy-paste goals that terminate cleanly, plus an audit prompt for the finished run
• A four-step check that proves the result without reading every changed line
• A failure table: what stalls or fools a goal run, and how to recover

How does /goal decide a run is finished?

A normal agent turn ends when the model decides it has said enough. /goal replaces that with a condition and a loop: the agent plans a step, makes the change, runs your checks, and then something asks “does the condition hold?” If not, the next turn starts without you.

That “something” is the part that differs:

	Claude Code	Codex	Cursor
Who judges done	A separate small fast model (Haiku by default on the Claude API) reads the transcript after every turn	The agent doing the work runs a built-in completion audit, then marks the goal complete itself	Not documented (checked 2026-08-28)
Verdicts	Not yet met · met · impossible	Complete · blocked (agent); paused (you); stalled, usage-limited, budget-limited (runtime)	—
Controls	/goal <condition>, /goal, /goal clear	/goal <objective>, /goal, /goal edit, /goal pause, /goal resume, /goal clear	/goal [objective]
Stops on its own when	Met or judged impossible (goal cleared), an error you have to fix (goal cleared); stall detection or a rate/usage limit pauses it with the goal still set	Complete, blocked after the same blocker in three consecutive turns, a usage limit, or a goal token budget	—
Runs without approval prompts	claude -p "/goal …"	Interactive session with --approve-for-me (no headless /goal form verified in codex exec 0.157.1)	Check your build
Available since	v2.1.139	goals stable and on by default in 0.157.1	2026-08-19, marked “Rolling out” (still, checked 2026-10-12)

Sources: Claude Code goal docs (checked 2026-09-26, CLI 2.1.283); Codex codex features list and the goal prompts shipped in the codex-cli 0.157.1 binary (checked 2026-09-26); Cursor’s CLI slash-command reference (checked 2026-08-28).

Two consequences follow. In Claude Code, the evaluator does not run commands or read files: it judges only what the agent printed. In Codex, the judge and the worker are the same model, so a well-worded audit is still self-assessment. In Cursor, nothing documented checks the objective at all. In all three, the independent proof has to come from somewhere else: a test command, a hook, or CI. The proof section below shows how.

Start a goal run in each tool

Claude Code

1. Pick the permission mode first. A goal does not change your permission mode, so a Manual-mode session stops at the first unapproved npm test. Interactive sessions on v2.1.283 and later (both release channels on 2026-10-12) start in auto mode unless settings disable it or the model does not support it. claude -p starts in Manual mode, except on third-party providers or with telemetry off, where it starts in auto mode from v2.1.285. See permissions, sandboxes and approval modes.

2. Set the goal. Type /goal followed by the condition (up to 4,000 characters). The first turn starts immediately; you do not send a separate prompt. One goal is active per session, and a new one replaces the old.

3. Watch the verdicts. Each evaluator verdict appears in the transcript; press Ctrl+O for the reason. /goal with no argument shows the condition, elapsed time, evaluated turns, token spend and the latest reason.

4. Stop or resume. /goal clear removes the goal. A goal still active when the session ends is restored by --continue or --resume, with the turn count, timer and token baseline reset.

For an unattended run on your own branch, allow only the tools the condition needs and cap the spend:

# Terminal, on a branch you own
claude -p "/goal every file under src/components imports useAppStore, not useStore; \
'npm run typecheck' exits 0 and 'npm test' shows 0 failed. Do not edit tests/. \
Stop after 25 turns." \
  --allowedTools "Read,Edit,Bash(npm test *),Bash(npm run typecheck *)" \
  --max-budget-usd 10 \
  --output-format stream-json --verbose

--max-budget-usd works only with -p, and it is the hard ceiling the “stop after 25 turns” clause is not. Without stream-json, nothing prints until the run ends. /goal is part of the hooks system, so it is unavailable in an untrusted workspace or when disableAllHooks or managed allowManagedHooksOnly is set; the command says why. The full Claude Code reference is goal workflows with /goal in Claude Code.

Codex

1. Confirm goals are on. Run codex features list; a default codex-cli 0.157.1 install reports goals stable true. If someone ran codex features disable goals, undo it with codex features enable goals.

2. Start an isolated session with automatic approval review. --worktree keeps the run off your working tree, and --approve-for-me routes approval requests through automatic review in the workspace-write sandbox, so the goal does not wait on you for each command:

   # Terminal, in the repository
   codex --worktree --approve-for-me

3. Set the goal. In the session, type /goal followed by the objective. Codex tracks tokens used and elapsed time against it.

4. Steer it. /goal shows status and usage; /goal edit rewrites the objective in place; /goal pause and /goal resume stop and restart it; /goal clear removes it.

Codex decides completion itself. Its goal instructions (0.157.1) tell the agent to treat completion as unproven, map every requirement in the objective to evidence such as command output or test results, and mark the goal complete only when that evidence covers every requirement. It marks a goal blocked only after the same blocker repeats for three consecutive goal turns. The TUI reports Goal paused, Goal stalled or a usage-limit stop; each resumes with /goal resume. A goal can also carry a token budget, and when it runs out the turn stops with Goal budget reached.

Because the worker grades itself, name the proof commands in the objective and re-run them outside the session.

Cursor

Cursor’s CLI reference lists /goal [objective] as “Give the agent a long-lived objective to work towards until it’s fully complete. Rolling out.” (checked 2026-08-28 and again 2026-10-12; the 2026-08-19 changelog introduced it). Availability depends on your build, so confirm the command appears in /help before you plan around it.

1. Check that your build has it. Run /help in the Cursor CLI and look for /goal.

2. Put the gate inside the objective. Cursor’s reference does not describe an evaluator (checked 2026-08-28), so the agent doing the work also decides when to stop. Name the exact command that proves completion and ask for its output as the last step.

3. Add a deterministic gate outside the agent. A required CI check or a pre-merge test run is what makes the result trustworthy, not the wording of the objective.

For recurring work Cursor ships /loop as a bundled skill (Cursor 3.5, 2026-05-20), and for cloud-side schedules and event triggers it has Automations (Scheduled, Source control, Slack, Webhook, Linear, Sentry, PagerDuty; checked 2026-08-28). Both are covered in the /loop command and background and cloud agents compared.

How do you write a goal the agent can finish?

The run is decided before it starts, in the condition. Five rules carry most of the weight:

1. One objective, one finish line. “Migrate the API and improve coverage” gives the judge two targets, and the run thrashes between them. Split it into two goals.
2. Make the finish line a command. “Looks good” is not checkable; “npm test shows 0 failed and 0 skipped” is. In Claude Code the evaluator only sees output, so ask for the summary line to be printed.
3. Name what defines correct. Point to the spec, the migration guide and one already-migrated file. An agent that guesses the target wanders.
4. State what must not change. “Do not edit tests/” and “Do not touch src/auth/” are the constraints a loop breaks first when a test is hard to satisfy.
5. Bound the run. Add a turn or time clause (“stop after 25 turns”), and in Claude Code headless runs a --max-budget-usd cap.

Copy-paste goal: API migration with a parity gate

/goal Every file under src/components/ imports useAppStore instead of useStore.
Read docs/migration/store.md and the migrated example src/components/Header.tsx first.
Done when: `grep -rl "useStore" src/components` prints nothing, `npm run typecheck`
exits 0, and `npm test` shows 0 failed and 0 skipped. Print each command's summary
line as proof. Do not edit anything under tests/ or src/store/. After each turn,
append one line to MIGRATION_LOG.md: files migrated, files left. Stop after 25 turns.

Copy-paste goal: fix a bug you can reproduce

/goal `npm test -- tests/checkout/rounding.test.ts` passes, and the full suite
still shows 0 failed. The bug: orders with three or more discount lines total
one cent too high. First write a failing test that reproduces it, show it failing,
then fix the cause in src/checkout/. Do not change existing assertions. Print the
failing run and the passing run. Stop after 15 turns and report the root cause.

Copy-paste goal: acceptance criteria from a spec

/goal Every acceptance criterion in specs/export-csv.md is met, each one proved by
a named test in tests/export/ that you show passing. Done when `npm test --
tests/export` shows 0 failed, `npm run lint` exits 0, and you print a table mapping
each criterion to its test name. Do not change specs/export-csv.md. If a criterion
is ambiguous, stop and list the question instead of guessing.

Writing the criteria themselves is covered in acceptance criteria agents can verify.

How do you prove a goal run did the job?

A “met” or “complete” verdict is the agent’s claim, judged from its own transcript. Prove it with evidence the loop could not produce by itself:

1. Re-run the gate outside the session. Push the branch and let CI run the same tests, type check and lint on a clean checkout. That run is the proof; the transcript is not.

2. Check the constraints held. Run this in the terminal; adjust the paths to what the goal promised not to touch:

   git diff --stat main...HEAD -- tests/ src/store/ package.json

   Empty output means the oracle and the protected code are untouched. Loops are good at making tests pass by weakening them; protecting the oracle adds deny rules and hooks that stop it at the source.

3. Review by risk, not by line. Run a review agent on the branch, then read only what it flags and anything in authentication, payments or data deletion.

4. Attach the evidence. Put the final goal status (condition, turns, token spend), the CI link and the git diff --stat output in the pull request. The evidence bundle defines the full contract.

The developer who set the goal signs off, because they own the condition and the judgement that it described the right outcome. A tech lead standardising goal runs reviews the condition templates and the gates, not every diff they produce.

Copy-paste prompt: audit a finished goal run

The goal reported complete. Before I merge, prove it independently. Report only;
do not fix anything.
1. Run `git diff --stat main...HEAD` and list every file changed outside the paths
   the goal allowed.
2. Run the full test suite, the type check and the linter from scratch, and show
   each summary line.
3. List every test you added, deleted, skipped or whose assertions changed, with
   the reason for each.
4. For each requirement in the goal, name the evidence that proves it, or say
   "not proven".

Run the audit in a fresh session or a different tool, so the model that did the work is not the one grading it.

When should you use /goal instead of /loop or a framework?

You need	Use	Why
Work that converges on a checkable end state in one session	/goal	Built in, bounded, with a verdict per turn
The same prompt on a cadence: poll a deploy, watch a PR	/loop	Runs on an interval, with no single finish line
A deterministic check after every turn, in every session	A Stop hook (hooks automation)	A script decides, not a model
Overnight multi-session builds with state on disk	Autonomous loops (Ralph, GSD Core)	Survives many sessions; needs a sandbox
Work that runs with your laptop closed	Background and cloud agents	Routines, Codex cloud and automations, Cursor Cloud Agents

A common pairing: a /goal run drives a feature to “tests green”, then a /loop watches the resulting pull request for CI failures and review comments.

What breaks in /goal runs, and how do you recover?

Symptom	Cause	Recovery
The goal never completes although the work looks done	The agent never printed the proof the condition names	Put the proof command in the condition and ask for its summary line
The run reports done after one green test file	The condition accepts partial evidence	Require totals: “0 failed and 0 skipped across the whole suite”
Tests pass because tests changed	Nothing protected the oracle	Add “do not edit tests/” plus deny rules; check with git diff --stat
Claude Code clears the goal as impossible	The condition contradicts a constraint, or the proof command cannot succeed here	Read the recorded reason, run the command yourself, fix the conflict, set the goal again
Codex shows Goal stalled or marks the goal blocked	The same blocker repeated across turns	Fix the blocker (a missing secret, a failing service), then /goal resume, or /goal edit to narrow the objective
The run waits at every command	Manual permission mode, or no approval review in Codex	Use auto mode in Claude Code or --approve-for-me in Codex, inside a sandbox
Token spend keeps climbing	No stop clause, or an unreachable end state	Check /goal for spend, then /goal clear; always pass --max-budget-usd in claude -p runs
Cursor’s run stops early and says it is done	No documented evaluator; the worker decided	Re-run the gate command and let CI decide

Run unattended goals where damage is contained

A goal loop does whatever satisfies its judge. Run it on a branch or worktree, in a sandbox, with no production credentials in the environment, and state in the condition whether the agent may push, delete or deploy. Never pair /goal with --dangerously-skip-permissions or --dangerously-bypass-approvals-and-sandbox outside a disposable, network-restricted sandbox.

Where to go next with goal-directed runs

Goal workflows with /goal in Claude Code The Claude Code deep dive: check-ins, retries, evaluator model and cost.

The /loop command Run prompts on a cadence: the interval-based counterpart to /goal.

Hours of autonomy: autonomous loops Ralph loops, GSD Core and sandboxed overnight builds.

Protect the oracle Stop a loop from passing by editing the tests.