Interactive mode

ks on its own, at an interactive terminal, opens the app: a home screen of your agents and, for each agent, a window you stay in. For a script, a pipe, --json or --no-input, ks prints its usage instead. The app uses the same service routes as the commands.

The home screen

The home screen lists your agents, one line each: the agent’s name, its session, what it is doing and how long ago it last reported. Agents that need you (waiting on a permission request, failed, or needing recovery) come first and are marked ⚑. Plain sessions, which have no agents, are listed last.

Key	What it does
↑ / ↓ (or k / j)	Move the selection
Enter	Open the selected agent’s window
n	Start a new agent session: name the agent (Enter keeps `main`); the app uses your enabled Anthropic key, starts a machine and opens the window
r	Refresh the list (it also refreshes itself every 10 seconds)
q, Ctrl-C, Ctrl-D	Quit the app; your agents keep working

Opening something other than a running agent:

A paused agent. Opening it never wakes it. The window offers r to resume the session (billing resumes) and Esc to go back.
An agent that needs recovery. The app prints what happened and the actions that recover it, then returns to the home screen.
A plain session. It has no agents; the app names its terminal, ks attach <session>, which runs outside the app.

The agent’s window

The window is the agent’s conversation. What has happened scrolls above, in your terminal’s own scrollback, so you can scroll, search and copy it as usual. Below it are three lines that stay in place: a permission prompt when one is waiting, the input line, and the status line.

You: what you typed, shown as you send it, with the task it became (queued, then running).
The agent: its replies in full, under its name.
Tools: one short line per tool the agent runs: ⎿ when it starts, ✓ when it finishes, ✗ with the reason when it fails.
Instructions: ● finished, or ✗ failed with the agent’s own summary.
Results: ↳ result, with its name, when a task records one (/results lists them).
A held queue: a line saying the queue is held, and why.
From elsewhere: an instruction another window, another person or an adviser sent is shown with who sent it.

Keys

Key	What it does
Enter	Send what you typed to the agent. Every Enter is a new message, recorded before it is sent, so a retry of the same send is never a second one
Esc	Interrupt the instruction in flight: the agent is asked to stop at a safe boundary, and the window says what state that left it in
y / n / d	With an empty input: allow once, deny, or show the details of the permission request on screen
↑ / ↓	Your earlier lines
Tab	Complete a `/` command; when several fit, list them
Ctrl-C, Ctrl-D	Clear the input; stop a `/` command that is running; twice within 2 seconds on an empty input, leave the window (the agent keeps working)
Ctrl-U	Delete from the start of the line to the cursor
Ctrl-W	Delete the word before the cursor
← / →, Ctrl-A / Ctrl-E, Home / End	Move the cursor; start and end of the line

A bracketed paste goes into the input as text, however many lines it has. It never answers a permission request and runs nothing by itself: Enter sends it, and a line that starts with / is then a command.

The status line

The status line reads the service’s own view of the agent every few seconds:

Part	Meaning
● Working, Ready, Waiting for approval …	The agent’s activity as its supervisor last reported it
unchanged 2m	The supervisor is live and has reported no change for that long (shown after 15 seconds)
STALE: last known	Nothing has been heard for more than 15 seconds and no live supervisor stands behind the last report, or a working agent has gone quiet: the word shown is the last known one, not the current one
queue N	Instructions waiting behind the current one
N waiting for you	Permission requests to decide
saved … ago / not saved yet	The session’s last checkpoint
N tokens, or model $N.NN	Model tokens the gateway metered for this session; a dollar figure instead, only where the service states one. Never $0 for an unknown cost
you control / watching	Whether this window steers the agent
⚑ N other agent(s) need you	Another of your agents waits on you: `/switch` to it

Permission requests

When the agent asks to run something that needs your permission, a box opens above the input with the exact action. y allows it once and n denies it; d prints the request in full: the action, the instruction it was asked for, what it touches and what deciding costs. With several waiting, the box says how many, and they are answered one at a time. How a decision is checked: approvals and control.

While you were away

Opening an agent again starts with one line about what happened since this computer last showed it: instructions finished and not finished, results produced, and permission requests waiting now, for example “While you were away (since Sep 30 15:27): 1 instruction finished”. The app keeps only where you left off (a position in the agent’s journal and the time), never the conversation’s text.

Several windows, one controller

An agent is steered by one window at a time; another window on the same agent watches, and /take takes control. See one window steers.

/switch <agent> opens another of your agents without going back home. It looks in this session first and then in all your sessions; when two agents have the same name it lists them and asks for the session instead of choosing.

Commands inside the app

Every ks command except four runs inside the window as a / command, with this session and agent filled in for you: /queue, /results, /diff <result>, /session checkpoints, /cruise proposal list. See slash commands for how they run and which four do not.

When the app is not the right tool

Scripts and CI use the commands directly: ks run --agent --task "..." --json starts an agent session and hands it its first instruction in one step. See common workflows.
Plain sessions (started by ks run without --agent) have no agents. Their terminal is ks attach <session>, outside the app.