Session Management

# Session Management Kit uses a tree-based session model that supports branching and forking conversations. ## Session storage Sessions are stored as JSONL (JSON Lines) files: ``` ~/.kit/sessions//_.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. ## 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 - **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. ## 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: ```bash kit --no-session ``` ## Resuming sessions ### Continue most recent ```bash kit --continue kit -c ``` ### Interactive picker Choose from previous sessions interactively: ```bash 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 ```bash 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 ` | 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: ```bash 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 ` - **Model** — Set via `/model ` or the model selector - **Thinking level** — Set via `/thinking ` or Shift+Tab cycling These preferences are restored on next launch. Precedence: CLI flag > config file > saved preference > default.