KodaCode
Coming soon
Docs/Working with the agent

Sessions

Start, switch, search, rewind and compact the conversations you have with the agent.

A session is one conversation with the agent in one project. Sessions keep running when you switch to another session or project, and everything they did stays in the transcript.

See it in action on the Sessions page.

Start and switch

  • New session: ⌘N, /new, or the New session button in the top bar.
  • The sessions dock groups sessions under Attention (waiting for you), This project and All sessions.
  • Sessions (⌘O, /sessions) opens every conversation KodaCode has kept. Resuming one switches to its project. Filter them by text and page through older ones.

The top bar

ControlWhat it does
Project switcherSwitch project (⇧⌘O).
ModelThe model for the next message. When no provider exists, you can add one here.
AgentThe agent this session runs as, chosen when it started. Default agent unless you pick a session agent.
Build / PlanBuild makes changes. Plan designs them first, read-only. See Plan mode.
Tool callsHow many tool calls this session has made. Click it to open the list.
StatusNo task, Working, Needs approval, Finished and so on.
StopStop session (Esc while a turn runs).

Steer or queue while it works

While a turn is running, the prompt box shows ↵ Steer · ⇧↵ Queue · Esc Cancel:

  • ↵ Steer sends your message into the running turn, after the current step.
  • ⇧↵ Queue holds it until the turn ends.
  • Esc stops the run.

Rewind

Every message you sent has Rewind to this message, available when the turn ends:

OptionWhat happens
Rewind conversation and filesBoth return to how they were before that message.
Rewind conversation onlyFiles stay as they are now.
Restore files onlyKeeps the conversation. KodaCode tells the agent which files it restored.
Rewind both, overwriting your editsShown when you edited files after that message. KodaCode replaces your edits.

Undo restore reverses a rewind. KodaCode keeps the snapshots in .koda/checkpoints/.

Compaction

The Context ceiling is 50% of the model's context window by default (in General settings). When the conversation reaches it, KodaCode compacts older messages into a summary. Run /compact to compact yourself. A Compacting context card shows the work. Then Context compacted shows what was kept word for word. The summary keeps:

  • the session's intent
  • what was done
  • the artifacts and next steps
  • about 6,000 tokens of your own words

KodaCode also shortens long tool results as they age. The agent can get one again in full with its retrieve tool.

Searching earlier sessions

The agent can search and read this project's earlier sessions with its search_sessions tool. So you can say "do it the way we did last week". You can browse them yourself with /sessions.

Forgetting sessions

Select sessions in the Sessions screen and forget them. "This cannot be undone. Each session goes with the work it started." A session whose background task is still working is kept.

Closing KodaCode with work running

If goals, automations or MCP tasks still run when you close the window, KodaCode asks what to do:

  • Keep running after closing
  • Pause and close: the jobs resume the next time KodaCode starts.
  • Stay in Koda

Set a default in General → Close behaviour. On macOS, ⌘Q never prompts, so Ask pauses the jobs.