Skip to main content
A normal turn ends when the model stops. A goal does not. /goal attaches one objective to the session, and the agent keeps working toward it across turns, planning, acting and verifying, until it can show evidence that the work is done, until you pause or clear it, or until its turn budget runs out. The objective is session state, so it survives the end of a turn, context compaction, and closing and resuming the terminal app. This page covers the commands, the chip that reports progress, the five states a goal can be in, how completion is decided, the turn budget, where the goal is kept, and when a goal is the right tool instead of a single turn or a headless run.
/goal is a recent addition to the CLI. If it does not appear when you type /, run cortex upgrade and try again.

​
Set a goal

1

State the objective

Type /goal <objective> in the composer. Describe an outcome that can be checked, not a single edit: ship the rate limiter and prove it with tests rather than open the rate limiter file.
2

Watch the chip appear

A goal chip appears immediately after the mode chip on the composer, reading Goal · 0/8 before the first turn and counting up from there.
3

Let it run, and check in

The agent continues between turns while the goal is active. Type /goal on its own at any point to see the objective, the state, the progress so far and the remaining budget.
4

Stop it when you want to

/goal pause stops the automatic continuation and leaves the objective in place. /goal resume picks it up again. /goal clear deletes it.

​
Commands

A reserved word is only special when it is the entire argument. /goal pause the deploy sets an objective called pause the deploy; it does not pause anything. To pause, type /goal pause and nothing else.

​
The chip and the five states

The chip sits next to the mode chip on the composer border, so the goal is visible in every turn without opening a panel.

​
Completion is evidence-based

The agent reports progress through a dedicated UpdateGoal tool rather than by saying it is finished. That call carries a status of active, blocked or complete, optionally a progress note and a reason, and optionally evidence. Each piece of evidence has a kind of file, command or test, plus a detail naming the file, the command or the test in question. Two rules follow from that, and they are the point of the feature:
  • Marking a goal complete requires a reason and usable evidence. A confident paragraph is not enough to move the chip to Goal · done.
  • The model cannot pause a goal. active, blocked and complete are the only states it can set. Pausing is yours alone.
A goal does not change what the agent is allowed to do. Every turn it takes still runs under the mode you are in, your approval policy and the sandbox, so commands that would prompt for approval still prompt. See Modes and permissions.

​
The turn budget

A goal carries a turn budget, 8 turns by default, which is the right-hand number on the chip. Close to the limit the next continuation is asked to wrap up what it has rather than open new scope. When the budget is used up the goal moves to budget_limited, the chip reads Goal · budget, and the automatic continuation stops; set the goal again if you want it to carry on with a fresh budget. For work that should run unattended with a hard ceiling instead, use a headless run with its own turn and time limits. See Headless and one-shot runs.

​
Where the goal is kept

The goal is written next to the rest of the session’s files, in the Cortex home directory:
Because it is a file beside the session, resuming the session reloads the objective, the state and the progress, and compacting the conversation does not lose it. See CLI sessions and Data locations.

​
When to use a goal