---
title: Session Management
description: How Kit persists and manages conversation sessions.
---

# 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/<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.

## 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 <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:

```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 <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.
