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
| Control | What it does |
|---|---|
| Project switcher | Switch project (⇧⌘O). |
| Model | The model for the next message. When no provider exists, you can add one here. |
| Agent | The agent this session runs as, chosen when it started. Default agent unless you pick a session agent. |
| Build / Plan | Build makes changes. Plan designs them first, read-only. See Plan mode. |
| Tool calls | How many tool calls this session has made. Click it to open the list. |
| Status | No task, Working, Needs approval, Finished and so on. |
| Stop | Stop 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:
| Option | What happens |
|---|---|
| Rewind conversation and files | Both return to how they were before that message. |
| Rewind conversation only | Files stay as they are now. |
| Restore files only | Keeps the conversation. KodaCode tells the agent which files it restored. |
| Rewind both, overwriting your edits | Shown 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.