Runners

KeepState is not tied to one coding agent. A session is a durable machine; what runs inside it is a program you choose. In an agent session, that program is the agent’s runner: the program that drives the model, started and supervised on the session’s own machine, calling the model with your key. Everything else in these docs (the app, instructions, permission requests, results, advisers, checkpoints and forks) works the same whatever the runner is. This page is the one place that says which runners exist. The browser console calls an agent’s runner its harness.

Agent sessions

An agent session runs a runner only after that runner has been certified: a recorded run has shown that every method the agent’s supervisor uses to drive it behaves as the supervisor reports it, on a pinned version. Two runners are certified today: Claude Code and Codex CLI.

What that certification covers, and what it does not:

• Covered, for Claude Code at version 2.1.296 (and at 2.1.251, which the sessions created before 2026-10-14 keep) and for Codex CLI at 0.162.1: the supervisor starts the runner, sees it become ready, hands it an instruction, relays its permission requests, interrupts it, reports each tool it runs, reports how each instruction ended, lets it consult an adviser, and saves and restores it at a safe boundary.
• Not covered: any other version of either runner; running Claude Code under a separate unprivileged user; and a mode built on a vendor’s agent SDK instead of the runner’s own program, which is not built.
• Where Codex CLI differs from Claude Code: it can type into a command it started earlier without asking first, which KeepState sees only afterwards, then stops the instruction and leaves it for you to decide; it applies command rules of its own, which can turn down a command after you approved it and leave the instruction open until you stop it; and its own sub-agents are refused.
• Other runners are not built or certified for agent sessions. When one is, it is added to the table above, and nothing else in these docs changes.

/status in the app (from a terminal, ks agent view <agent>) names the runner the agent started, with its version; anything other than the certified runner at the certified version reads not certified there.

Claude Code or Codex CLI

Each runner calls its own provider, on your own key: Claude Code calls Anthropic, and Codex CLI calls OpenAI with gpt-6-luna, its one offered model. KeepState offers no key of its own for either: add an OpenAI key to your account before you switch to Codex CLI (keys). The browser console’s new-agent form starts an agent on Claude Code; for Codex CLI, pause the session and switch its harness, or start the agent on Codex CLI from a terminal:

ks run --agent --harness codex --agent-name main

The model the runner calls is chosen when the session is created (ks run --agent --model, or the browser console’s new-agent form; the ratified table’s default entry when none is chosen, and ks cruise models lists the table and says which entries are offered) and changes while the session is paused (ks session model, or Change model on the browser console’s session page), in effect from the next resume. A session started since Codex CLI was offered can also change its model while running, from the Model menu in the agent’s header, from the agent’s next instruction on; the menu says which applies. A switch of harness moves the model to one of the new harness’s models.

Switch a paused session’s harness

In the browser console, the agent’s header shows Model and Harness. Pause the session, open Harness and choose the other runner. The dialog that opens names the model on the new harness and what stays and what changes, and can resume the session once the switch is done. From a terminal:

ks session harness <session>
ks session harness <session> codex

The first prints the session’s harness, its model and whether it can switch now; the second switches a paused session (--model names the model on the new harness). The browser console and the client make the same change.

• Kept: the session’s files, its queued instructions, and the conversation so far, readable as before.
• Changed: the runner, its model and the conversation: the next instruction starts a new one in the new runner, which cannot see the old one, and the handoff brief below covers what came before.
• Your key: a switch to Codex CLI binds your enabled OpenAI key if the session lacks one; without an enabled OpenAI key, the switch fails.
• Not possible: while running (pause first), for a session created before Codex CLI was offered (start a new session for Codex CLI; the old one stays as it was, files and conversation), or to an uncertified runner.
• Switching back: the same steps, with a new conversation and a new brief.

The handoff brief

A new conversation starts knowing nothing of the work so far, so KeepState prepares a handoff brief for the new agent, delivered with your next instruction:

• From KeepState’s own journal of the session: your instructions, where the work stands, the decisions taken, the constraints you set, the files and commands involved, what remains open, known problems, and each permission request so far with how it was decided.
• A short summary, written by the previous runner’s smallest model on the session’s own key: your provider bills that call, and KeepState puts no price on it. If no summary arrives, the brief goes out with KeepState’s part alone, marked as such.
• Checked by code, line by line: a line without a citation of the session’s journal, or one repeating an order no person gave, gets dropped, and secrets get removed.
• No permissions: no approval transfers, so the new agent asks again before every action; the brief informs and never instructs, and the files in the workspace stay the authority.

The new agent can also look up the session’s earlier journal on demand. Both runners read the same project instructions: Codex CLI reads the file Claude Code uses, and Claude Code also reads AGENTS.md. You see the brief in the conversation after the switch, with its size and the model that wrote it; ks session brief <session> prints the latest switch’s brief as the new agent received it.

Start an agent

ks

Press n, name the agent, and type what you want done. Or, in one command that also opens the window:

ks run --agent --agent-name main --task "Upgrade the payment client and keep the tests green" --open

Either way, the session is bound to your provider key, its machine starts, and the agent’s state is starting (the client prints “supervised and waiting for its first instruction”) until it takes one up. See the quickstart.

How you work with it

You talk to the agent in the app’s window; it asks before it acts and keeps working when you leave; its results wait for you to review and apply. An agent session has no shell: ks exec and ks attach are refused there. See agents, tasks and results, approvals and control and, for pausing, checkpoints and forks, common workflows.

Plain sessions

A plain session (ks run without --agent) runs whatever program you start in it, and you drive it with the session commands from a terminal: ks attach to watch it, ks exec to run one command, ks checkpoint to save, ks wake to resume, ks fork to branch and ks meter for its spend. Two programs have been frozen and resumed there in recorded tests: Claude Code and aider 0.86.2, with what each test showed on the compatibility matrix. A plain session does not have agents, permission prompts, results or the app’s window; those come with agent sessions.

ks run --image claude
ks attach <session>

Migrate a plain session

A plain session started before agent sessions existed can become an agent session (the migration commands call it a legacy session). In a terminal:

ks session migrate <session>
ks session migrate <session> --confirm <digest>

The first command shows the preview: the runner, the keys, the checkpoints, what is preserved, the checkpoint to roll back to, and what each plain-session command does afterwards. The second applies exactly that preview, or nothing. A running session must be saved and stopped first. Afterwards ks exec and ks attach are refused for that session. ks wake resumes it as ks agent resume does, ks fork names ks session fork and its plan, and ks kill shows the session’s deletion plan and, in a terminal, deletes it once you type the session’s name, as ks session delete does.