Sessions & Resuming

A session captures a conversation: the project it belongs to, the message history, the model configuration, and — for the TUI — the latest plan and shared task list. Sessions let you stop and resume work later.

How sessions are created

• In the TUI, launching kolega-code . starts a fresh session by default. Your work is saved when you quit (Ctrl+Q, /quit, or /exit).
• With ask, a session is only persisted if you pass --save or --session. See kolega-code ask.

Sessions are stored as JSON, one file per session, in your state directory. See Settings & API Keys for the exact location and the KOLEGA_CODE_STATE_DIR override.

Resuming in the TUI

On a fresh launch, the startup card shows up to three recent sessions from the same project. Click a title, or focus it with Tab and press Enter, to resume. An already-open session stays locked: close it in the other instance, then click again. Resuming asks for confirmation before discarding an unsent draft or attachments, or changing to the session’s saved worktree. These choices disappear once you start a conversation and do not return when you clear the thread.

You can also choose a session when launching:

# Resume the most recent session for this project
kolega-code . --resume

# Resume a specific session using the Resume ID from `sessions list`
kolega-code . --resume <session-id>

A few rules:

• Quitting the TUI prints the exact resume command for the session you just closed, including its ID — copy it to be sure you get this session back.
• --resume with no ID resumes the latest session for the project. If there are none, the CLI reports that.
• sessions list labels the session ID to copy as Resume ID. Previously saved commands that use a thread ID remain supported for compatibility.
• A session belongs to the project it was created in — resuming it from a different project directory is rejected.
• --new forces a fresh session (this is the default behavior).
• --session <ID> is a legacy alias for --resume <ID>; you can’t combine --resume and --session in the same command.

Managing sessions

Use the sessions subcommand to list, delete, or export saved sessions:

kolega-code sessions list --project .
kolega-code sessions export <session_id> --output run.json
kolega-code sessions delete <session_id>

Note

All CLI sessions use the CLI-specific coding-agent prompt, including resumed ones. Resuming restores the conversation history so the agent picks up with full context. An active goal is also saved with the session and restored on resume, so the autonomous loop continues where it left off. An active scheduled loop is restored the same way, keeping its schedule, iteration count, and expiry — a loop that expired while the session was closed is retired instead of fired, and a fire time that passed triggers exactly one iteration once the session is idle.