Common workflows

Each workflow starts in the ks app (ks on its own) and gives the terminal command for the same step. Inside an agent’s window, a / command runs the ks command of the same name with this session and this agent filled in; from a terminal, pass --session <session> yourself. Every command, in both forms, is on the CLI reference.

Fix a bug and apply the result

Open the app and start an agent session (n on the home screen), or open an agent you already have.
Describe the bug in the input: what fails, how to reproduce it, and what “fixed” means. Press Enter.
Watch the conversation, or leave (Ctrl-C twice) and come back: the window opens with what happened while you were away.
/results lists what the task produced; /diff <result> shows the changeset against the base it was made from, and its digest.
Apply it to your project:

/apply <result> --confirm <digest>

From a terminal in your project directory, ks result apply <result> shows the changeset and asks for the digest. Either way it writes only onto the recorded base, all or nothing, and refuses a file that has changed since. An interrupted apply is put back with ks result apply <result> --recover. See agents, tasks and results.

Answer permission requests

An agent asks before it runs anything that needs permission, and waits. In the app the request opens as a box above the input: y allows it once, n denies it, d shows everything about it. /approvals lists every request waiting in this session. From a terminal:

ks approval list --session <session>
ks agent approve <request> --session <session>
ks agent deny <request> --session <session>

How a decision is checked, and who may decide: approvals and control.

Pause, then resume

Pausing saves the session and parks it: session time stops, and only storage is billed until you resume.

In the app: /pause, and /resume to continue.
From a terminal: ks agent pause <agent> --session <session> and ks agent resume <agent> --session <session>.

Opening an agent never wakes a paused session: the window says it is paused, r resumes it (billing resumes), and Esc goes back. Adding credit does not resume a session by itself.

Save, fork and restore

A checkpoint is the whole session saved at one moment: memory, disk and processes. Pausing saves one; so do automatic saves, when you turn them on:

/session checkpoint-policy --on --interval 15

KeepState keeps four checkpoints of each session usable: the three most recent, and the oldest one from within the hour before the newest, so the four reach back up to an hour. You can restore, resume or fork from any of the four; older ones move to the list of earlier saved points, marked no longer kept. Only one of them counts toward storage (usage).

In the browser console, a session’s page lists them as saved points, newest first, each with what it allows:

while the session runs, Restore to here takes the session back to that point, and Fork from here branches it;
while it is paused, Resume continues from the point the session last saved or was restored to, Resume from here restores another point and continues from it, and Fork from here branches it.

/checkpoints (from a terminal, ks session checkpoints <session>) lists the checkpoints a fork or a restore may name, with whether each is usable now and its position, newest first, and for any other, why it cannot be named. Neither ever picks one for you.

A fork branches a checkpoint into one or more new sessions, each with its own history. It starts as a plan and is carried out by the plan’s digest. Forking needs a paid plan.

/session fork --plan --checkpoint <checkpoint> --children 2
/session fork --execute <digest> --plan-id <plan>

A restore takes the session back to a checkpoint and says first exactly what continues from it. When work in flight is affected, it lists that work and waits for --accept-affected <digest>. After a restore to an older checkpoint, the newer ones stay usable, so you can come back to the newest; the next save becomes the newest point, and the rule above applies again from there.

/restore --checkpoint <checkpoint> --reason "try the other approach"

From a terminal, the same commands with ks and the session named: ks session fork <session> ..., ks session restore <session> ....

Ask an adviser

One of your agents can consult another of your agents, over a connection you make and can withdraw:

/adviser discover
/adviser connect <adviser> --confirm <session/agent>

The window fills in this agent as the one that asks. Limits, defaults and the terminal forms: advisers.

Approve an agent’s Cruise proposal

An agent can propose a Cruise job, listed by /cruise proposal list; nothing starts until you approve it. Approval goes through a draft: the service copies the session’s files, drafts the job on the proposal’s terms and computes its digest again, and you approve that digest. In the browser console, Review and approve on the session’s page does it; from a terminal, ks cruise draft create --proposal <proposal>, then ks cruise draft approve <draft>. See jobs your agent proposes.

Start a Cruise job in the browser console

New job on the browser console’s Jobs page, or Start a Cruise job from this session on a session’s page, drafts a Cruise job from one of your sessions or from a folder or archive you upload, and runs it once you approve its fingerprint. See start a job in the browser console.

Migrate a plain session

A plain session started before agent sessions existed can become an agent session, through a preview you confirm. See Runners.

Scripting

Every command takes --json for stable machine output and --no-input so it never prompts; a step that needs a confirmation then names the flag to pass (see confirmations). One command starts an agent session and hands it its first instruction:

ks run --agent --agent-name fixer --task "Make the failing test pass" --json

It binds your enabled Anthropic key (or the one --key names), submits the task once the agent is supervised, and returns. Follow the agent from a script:

ks agent status fixer --session <session> --json
ks task list --session <session> --json
ks result list --session <session> --json

Every change carries an idempotency key and leaves an operation record. When a reply is lost, the change is reported as outcome unknown until its record is read, never sent a second time: ks operation show <operation> reads it back. An instruction typed before a dropped connection is looked up by its submission id rather than sent again.