mirror of
https://github.com/mark3labs/kit.git
synced 2026-06-14 03:30:26 +00:00
ezynda3
134 lines
4.9 KiB
HTML
134 lines
4.9 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>Session Management | Kit</title>
|
|
<meta name="description" content="How Kit persists and manages conversation sessions.">
|
|
<link rel="canonical" href="/sessions">
|
|
<link rel="stylesheet" href="/assets/index-Di_r5hA0.css">
|
|
<script type="module" src="/assets/index-8qR0kq1Z.js"></script>
|
|
<script type="application/ld+json">{"@context":"https://schema.org","@type":"TechArticle","headline":"Session Management","description":"How Kit persists and manages conversation sessions.","url":"https://go-kit.dev/sessions","isPartOf":{"@type":"WebSite","name":"Kit","url":"https://go-kit.dev"}}</script>
|
|
</head>
|
|
<body>
|
|
<div id="tome-root"></div>
|
|
<div data-pagefind-body style="display:none"><h1>Session Management</h1>
|
|
# 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.</div>
|
|
</body>
|
|
</html> |