Codestin Search App

/goal is used to set a persistent goal for the current session, allowing the Agent to continuously and autonomously execute around it. This page lists all subcommands, parameters, and state behaviors. For a guide on using Goal mode, see Continuously Achieve Goals. Running /goal directly (without a subcommand) is equivalent to /goal status, which displays the current goal status.

Subcommands

Subcommand	Parameters	Description
`/goal`	`<description> [--turns <N>]`	Creates or updates a goal; without arguments, displays the current goal status. Does not change the Permission Mode.
`/goal status`	None	Displays the description, status, Elapsed Turns, and Elapsed Time of the current goal.
`/goal clear`	None	Removes the current goal.
`/goal pause`	None	Pauses the current goal.
`/goal resume`	None	Resumes a paused goal.
`/goal take`	None	Claims a goal owned by another session, transferring ownership to the current session.

/goal Parameters

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

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

Example:

/goal fix all failing unit tests and commit
/goal complete login module refactoring --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.

Status Fields

Goal status is persisted and includes the following fields:

Field	Description
`objective`	Goal description.
`status`	Status: `active` / `paused` / `complete`.
`maxTurns`	Maximum turn limit; it may be absent from Goals persisted by older versions.
`turnsUsed`	Elapsed Turns.
`timeUsedSeconds`	Elapsed Time (in seconds).
`ownerSessionId`	Session ID owning the goal (used for multi-session collaboration).
`planWasActive`	Whether it was in Plan Mode before the goal was activated (used for restoration).

Key Behaviors

Permission Mode Independence: Goal never changes the Permission Mode; tool approvals during execution follow the current mode. For unattended execution, switch to auto or yolo beforehand.
Cross-session persistence: Goals are persisted with the session. If the process is unexpectedly terminated while the goal is active, it will automatically downgrade to paused on the next startup, and can be reactivated using /goal resume.
Ownership: The goal records the Session ID that owns it. Other sessions must first use /goal take to claim the goal before they can update it. This prevents a new window from silently inheriting an unfinished goal from another session.
Plan State Restoration: If the goal was in Plan Mode before activation, /goal resume will also restore Plan Mode 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 Step

Goal mode guide: Continuously Achieve Goals.
Permission Mode description: Permissions.
All slash commands: Slash Command.

​Subcommands

​/goal Parameters

​Turn limit

​Status Fields