kit

Session Management

Kit uses a tree-based session model that supports branching and forking conversations.

This page is about conversation sessions — the JSONL transcript Kit saves so you can resume a conversation with --continue or --resume. Kit also has detachable sessions: a running kit process hosted by a daemon that you attach to and detach from, like tmux. Those are covered in Remote sessions. The two are independent — a detachable session saves its conversation exactly like a local one.

Session storage

Sessions are stored as JSONL (JSON Lines) files:

~/.kit/sessions/<cwd-path>/<timestamp>_<id>.jsonl

Path separators in the working directory are replaced with --. For example, /home/user/project becomes home--user--project.

Each line in the session file is a JSON entry representing a message, tool call, model change, or extension data. The tree structure allows branching from any message to explore alternate paths.

When a subagent is spawned from a persisted parent session, the child records its parent in the file header (parent_session_id, parent_session, and the originating subagent_task), so delegated work can be traced back to the session that spawned it.

Use /subagents to inspect retained child conversations without changing the parent conversation. This view uses in-memory run history; it does not load saved JSONL transcripts or restore history after a restart. Resume a child session through the subagent tool’s session_id parameter instead.

Compaction

When conversations grow long, Kit can compact them to free up context window space. The compaction system:

• Non-destructive: Old messages remain on disk for history; only the LLM context is summarized
• Full-context token estimation: Estimates count every message part — tool-call arguments, tool results, reasoning, and file attachments — not just plain text, so tool-heavy sessions trigger compaction on time
• Adaptive budgets: The response reserve and keep-recent budgets scale with the model’s context window and output limit instead of using fixed constants
• Anchored summaries: When a session compacts more than once, the previous summary is fed back to the LLM and updated incrementally instead of being regenerated from scratch
• File tracking: Tracks which files were read and modified across compactions
• Split-turn handling: Can summarize large single turns by splitting them
• Tool result truncation: Caps tool output during serialization to stay within token budgets

Use /compact [focus] to manually compact, or enable --auto-compact to compact automatically near the context limit.

Reactive compaction on overflow

Independent of --auto-compact, Kit always recovers from provider context-overflow errors reactively: it compacts the conversation and replays the failed turn once, replacing media attachments with text placeholders in the replayed request. Token estimates inevitably drift from real tokenizer counts, and a single huge mid-turn tool result can overflow the context even when the turn started under the limit — this safety net makes those cases non-fatal. Only when the replay also overflows does the turn fail, with a clear “conversation too large to compact” error.

Auto-cleanup

Kit automatically cleans up empty sessions on shutdown and when using /resume. A session is considered empty if it has no messages beyond the initial system prompt. This prevents cluttering your sessions directory with unused files.

To start fresh without creating a session file at all, use ephemeral mode:

kit --no-session

Resuming sessions

Continue most recent

kit --continue
kit -c

Interactive picker

Choose from previous sessions interactively:

kit --resume
kit -r

The session picker supports search, scope/filter toggles (all sessions vs. current directory), and session deletion. You can also open it during a session with the /resume slash command.

Open a specific session

kit --session path/to/session.jsonl
kit -s path/to/session.jsonl

Session commands

These slash commands are available during an interactive session:

Command	Description
/name [name]	Set or display the session’s display name
/session	Show session info (path, ID, message count)
/resume	Open the session picker to switch sessions
/export [path]	Export session as JSONL (auto-generates path if omitted)
/import <path>	Import and switch to a session from a JSONL file
/share	Upload session to GitHub Gist and get a shareable viewer URL
/tree	Navigate the session tree
/fork	Fork to new session from an earlier message (creates new session file)
/new	Start a new session (creates new session file)

Ephemeral mode

Run without creating a session file:

kit --no-session

This is useful for one-off prompts, scripting, and subagent patterns where persistence isn’t needed.

Sharing sessions

The /share command uploads your session JSONL to GitHub Gist (via the gh CLI) and prints a shareable viewer URL:

/share

The shared session includes:

• The system prompt that was active during the conversation
• The model used (e.g., anthropic/claude-sonnet-4-5)

The viewer displays this information in a collapsible “System Prompt” section at the top of the session, with the model shown as a badge in the header.

The viewer is available at https://go-kit.dev/session/#GIST_ID and supports all message types including text, reasoning blocks, tool calls, images, and model changes.

You can also load any JSONL session via URL parameter: https://go-kit.dev/session/?url=https://example.com/session.jsonl

Preferences persistence

Kit automatically saves your preferences across sessions to ~/.config/kit/preferences.yml:

• Theme — Set via /theme <name>
• Model — Set via /model <name> or the model selector
• Thinking level — Set via /thinking <level> or Shift+Tab cycling

These preferences are restored on next launch. Precedence: CLI flag > config file > saved preference > default.

This site is open source. Improve this page.