Goal Command Reference

/goal sets a persistent goal for the current session, letting the Agent keep executing autonomously around it. This page lists all subcommands, parameters, and state behavior. For the usage guide to Goal mode, see Working Toward a Goal. Running /goal directly (without a subcommand) is equivalent to /goal status, showing the current goal status.

Subcommands

Subcommand	Parameters	Description
`/goal`	`<description> [--turns <N>]`	Create or update a goal; without arguments, shows the current goal status. Does not change the permission mode.
`/goal status`	none	Show the current goal's description, status, turns used, and time used.
`/goal clear`	none	Remove the current goal.
`/goal pause`	none	Pause the current goal.
`/goal resume`	none	Resume a paused goal.

/goal parameters

/goal <description> [--turns <N>]

<description> (optional): a natural-language description of the goal. Omitting it shows the current goal status (equivalent to /goal status).
--turns <N> (optional): the maximum number of interaction turns. N must be a positive safe integer and may exceed 100; invalid values do not take effect. When the limit is reached, the Goal pauses automatically and can be continued with /goal resume.

Examples:

/goal Fix all failing unit tests and commit
/goal Finish the login module refactor --turns 20

Turn limit

Scenario	Effective limit
Create or replace a Goal with `--turns <N>`	`N`
Create or replace a Goal without `--turns`	The current Query's Goal default; `100` when the host does not configure one
Update the current Goal without `--turns`	The Goal's persisted limit is preserved
Restore a legacy Goal without `maxTurns`	An effective limit of `100`, without rewriting persisted data

An SDK host can set the Goal default when initializing a Query, then update or reset it while the Query remains open. A successful runtime update affects only Goals created or replaced afterward and does not modify the current Goal. Resetting restores the built-in default of 100. An explicit per-Goal --turns value always takes precedence over the Query default.

State fields

Goal state is persisted and includes the following fields:

Field	Description
`id`	The goal's unique identifier.
`objective`	The goal description.
`status`	Status: `active` / `paused` / `complete`.
`maxTurns`	The maximum turn limit; it may be absent from Goals persisted by older versions.
`turnsUsed`	Turns used.
`timeUsedSeconds`	Time used (seconds).
`createdAt` / `updatedAt`	Creation and last-update timestamps.
`planWasActive`	Whether Plan mode was active before the goal was activated (used to restore after resume).

Key behaviors

Permission mode is independent: Goal never changes the permission mode; tool approvals during execution follow the current mode. For uninterrupted execution, switch to auto or yolo beforehand.
Cross-session persistence: goals persist with the session. If the process is terminated unexpectedly while a goal is active, the next launch automatically downgrades it to paused, and it can be reactivated with /goal resume.
Plan state restoration: if Plan mode was active before the goal, /goal resume also restores the Plan state after a process restart.
Turn limit: when turnsUsed reaches the effective limit, the Goal pauses automatically. After a limit-triggered pause, /goal resume grants another 100 turns; resuming a Goal that was paused early does not extend its limit.

Next steps

Goal mode usage guide: Working Toward a Goal.
Permission modes: Permissions and Directory Trust.
All slash commands: Slash Commands.

​Subcommands

​/goal parameters

​Turn limit

​State fields