Sessions & History

Every conversation in the Blueprint AI panel is a session — a single JSONL file on disk that records every user message, assistant message, tool call, attachment, and permission decision in order. Sessions persist across editor restarts and are visible to every Blueprint AI panel tab in every editor instance.

Where sessions live

Sessions are stored per project under the AI service’s local data directory. For Claude:

~/.claude/projects/<project-key>/<session-uuid>.jsonl

<project-key> is a hashed version of your project’s absolute path, so the same project on different machines (or different paths on the same machine) keeps its own session list.

Each line is one event — user, assistant, tool_use, tool_result, etc. — readable with any JSON-aware tool. The JSONL is the source of truth; there is no internal binary format.

The Session Drawer

Click the history button on the left of the TopBar to open the Session Drawer — a popup list of every session for this project, newest first.

+-----------------------------+
|  Sessions            [x]    |
|  [ search... ]              |
|  * New Chat          2m ago |
|  * BP_Enemy setup    1h ago |
|  * Material work     3d ago |
|  * Old session       7d ago |
|                             |
|  [ + New Session ]          |
+-----------------------------+

Each row shows a derived title (the first user message, trimmed), the relative timestamp, and a delete button (×) on hover. Clicking a row switches the panel to that session — the message list re-renders from JSONL, attachments come back, the active mode and model are restored.

The drawer is backed by a real file watcher on the JSONL directory, so external edits, deletions, or imported sessions show up within seconds without a panel restart.

Search and filters

The search box at the top of the drawer filters live, matching against three axes simultaneously:

Title — substring against the derived session title
Content — substring against any user or assistant message
Tool — substring against any tool name used (e.g. create_blueprint shows every session that called it)

Results re-rank closest-match-first. Sessions also group by time: Today (< 24 h), Yesterday (24–48 h), This week (2–7 days), Older (> 7 days) — empty groups are hidden.

Replay

Switching sessions doesn’t just load text — the replay engine re-walks the JSONL and restores every UI state: message bubbles in order, ToolUse blocks with their final status badges, attachments visible as chips inside their original message, ModeSelector restored (agent, model, mode, effort), ContextRing updated to the recorded token usage.

If a session ended mid-stream (e.g. you closed the editor while the AI was generating), the replay marks the trailing message as interrupted and offers a Resume action — clicking it re-sends a continuation prompt to the AI.

New, delete, multi-tab

New — click + New Session in the TopBar, or type /new. A JSONL is created on the first user message; empty sessions never leave files on disk.
Delete — hover any row in the drawer and click ×. If you delete the active session, the panel falls back to the most recent remaining session or starts a new empty one. Bulk delete is exposed via the CLI — see CLI Commands.
Multi-tab — open more than one Blueprint AI tab from Window → Blueprint AI. Each tab holds its own active session, the on-disk store is shared. A session opened in tab A also shows in tab B’s drawer; deleting it in A moves B to a fresh session with a one-line notice. The token-usage ring and ModeSelector are per-tab, so opening the same session in two tabs lets you fork it experimentally.

Reading them externally

The JSONL is plain text — tail one with Get-Content -Wait / tail -f, pipe through jq to extract tool calls, diff two with any text-diff tool, or drop a .jsonl from a teammate into your ~/.claude/projects/<project-key>/ to import their session.