Sessions

Sessions are persisted per workspace in an append-only SQLite-backed runtime store.

Storage

By default the database lives at:

$XDG_DATA_HOME/kodacode/kodacode.db, or
~/.local/share/kodacode/kodacode.db

Override that with sessions.db_path.

The same database also stores derived session artifacts such as large tool results and background execution logs.

The search index is separate and defaults to $XDG_STATE_HOME/kodacode/search or ~/.local/state/kodacode/search.

Retention and deletion

retention.expiry_days does not auto-delete stored session history. It only expires derived artifacts and cache data:

tool-result blobs in kodacode.db
background execution logs in kodacode.db
persisted search-cache files on disk
app log files

Stored session history is retained explicitly. The TUI no longer exposes a session manager for deleting or purging saved sessions.

Timeline branching

Use /timeline when you want to try another approach from an earlier point in the current session.

The timeline dialog lists turns from the open session and shows related branch sessions in context. Branch rows use tree glyphs for nested lineage and show a selected-row preview with status, update age, parent turn, session id, and child branch count. If you explicitly summarize a branch, the preview shows the saved summary while it is fresh. Select a row and press:

Enter or b to create and switch to a new branched session
Enter on a parent or child branch row to open that related session
t to inspect that turn in the trace dialog
/ to search turn text, branch labels, ids, and row metadata
f to cycle filters, or 1 through 5 for all, completed, failed, with tools, and branches
Space, Left, or Right to fold and unfold nested branch sessions
s on a child branch row to generate or reuse a branch summary
e on a branch row to edit that branch session label
q or Esc to close the dialog

Branching is available only from completed turns. A running turn can still be highlighted and inspected, but runtime will not create a branch until the turn has a completion sequence. Failed or canceled turns count as completed because they have a stored terminal event.

The branched session keeps the same workspace roots and permission mode, records its parent session, parent turn, and parent sequence, then replays the original session history only through the selected turn. Later turns stay in the original session. /timeline uses that lineage to act as a lightweight session graph: child branches appear under the turn they branched from, deeper branches nest under their parent branch, and a branched session shows a parent row at the top.

Branch summaries are explicit. Opening /timeline does not generate them. When you press s, kodacode uses the configured utility model, caps input to recent final turns and existing history summaries, stores the result as a runtime artifact, and reuses it until the branch receives another event. Summary generation records utility branch-summary usage in the session’s cost data.

Easy example

This is a good default for one developer who wants session persistence and a clear warning before spending too much in one conversation:

sessions:
  budget: 5           # default: 0 (no limit)
  budget_warn: 0.8    # default: 0 (no warning)
  max_provider_requests_per_turn: 32  # default: 32

What you get:

the session can be resumed later
you get warned when estimated spend reaches 80% of the session budget
one turn cannot keep looping forever

Advanced example

This is a better fit for a heavy repo where sessions stay open for a long time and you want both long-context control and cross-session cost control:

sessions:
  db_path: /Users/you/.local/share/kodacode/monorepo.db
  budget: 20                        # default: 0 (no limit)
  budget_warn: 0.75                 # default: 0 (no warning)
  total_budget: 150                 # default: 0 (no limit)
  total_budget_warn: 0.8            # default: 0 (no warning)
  compaction_threshold: 0.8         # default: 0.8
  compaction_target_threshold: 0.60 # default: 0.60
  max_provider_requests_per_turn: 32            # default: 32
  max_output_continuations: 1       # default: 1, max: 2
  max_retries: 2                    # default: 2

Why this helps:

one repo can keep its own session database
per-session and cross-session budgets keep costs legible over time
history-summary compaction keeps long sessions usable instead of letting prompt replay grow unchecked
provider request caps and retry limits cut off wasteful turn churn

Resume behavior

KodaCode can reopen the latest workspace session instead of starting over:

kodacode --resume "continue from the previous session"

If the previous session is blocked on a permission request, resume continues that same turn and approval flow instead of inventing a fresh state.

Session controls

Useful config.yaml keys under sessions include:

db_path: where the SQLite event log lives; default ~/.local/share/kodacode/kodacode.db
budget: cost ceiling for one session in USD; default 0 (no limit)
budget_warn: fraction of budget at which to warn (0–1); default 0 (no warning)
total_budget: cost ceiling across all stored sessions in USD; default 0 (no limit)
total_budget_warn: fraction of total_budget at which to warn (0–1); default 0 (no warning)
response_style: default or terse; terse reduces ordinary model reply length and output token cost; default terse
max_provider_requests_per_turn: maximum provider requests in one turn; -1 removes the cap; default 32
max_output_continuations: automatically continue clipped provider output only on explicit length stops; 0 disables it; maximum 2; default 1
compaction_threshold: fraction of context limit at which older replayed history starts rebuilding into the saved History Summary; default 0.8
compaction_target_threshold: acceptance ceiling for that history-summary pass; must be lower than compaction_threshold; default 0.60
max_retries: provider retry attempts per turn; default 2

Why these settings matter

The advantage of session configuration is not just persistence.

budgets help keep experimentation affordable
warnings surface problems before a turn or a week of sessions gets expensive
history-summary compaction helps long-running sessions stay useful instead of degrading into context overflow
round caps and stall detection keep the runtime honest when a model stops making progress
a custom db_path is useful when you want one repo or environment to keep its own stored history

TUI session commands

/timeline: branch a new session from a completed turn in the current session
/compact: rebuild older session history into the saved History Summary now
/new: start a new session
/history: search recent prompts
/restore [turn-number]: restore writes from one turn

The important design choice is that session state is reconstructed from events, not from hidden UI-local state.