History Navigator

The History Navigator turns every Claude session into something you can browse, replay, and search. It reads Claude Code’s own session transcripts and presents them as a navigator: a rail of past sessions on the left, the conversation and tool calls on the right.

How it works

crystl parses the structured transcript Claude Code writes for each session (under ~/.claude). Those transcripts are read-only: crystl reads them on demand and never modifies or deletes them. (Separately, crystl maintains its own searchable timeline index of your history (see below), which also never touches the transcript files.)

The navigator is Claude Code-only for now. Codex and Antigravity CLI record their session history in different formats, so opening the navigator on one of those shards shows a Claude-only notice and crystl history returns nothing. Support for other agents’ transcripts may come later.

Open the navigator from the gem menu (click the ⋮ on the gem’s tab) and choose history.

Navigating a session

• The rail lists the gem’s sessions, grouped by date. Opening from a live shard drops you straight into that shard’s current session.
• Drilling into a session shows its moments, one per prompt, with a ‹ back to the session list.
• The right pane has Conversation and Tools tabs: the dialogue, and every tool call with its input and result (click a tool row to expand the full payload).
• Click a moment in the rail to jump the right pane to that point. As you scroll the conversation, the rail highlights the moment you’re looking at, so you always know where you are in time.

Searching

The search box at the top of the rail spans all of the gem’s sessions at once. It matches both conversation text and tool calls (tool names, commands, file paths, and output) so you can find the session where you ran a migration, or where Claude worked through a bug, even if you only remember a command or a filename. Each result is tagged by kind (prompt, reply, or tool); click one to open that session at the exact moment.

From the command line

crystl history reads a shard’s transcript (turns and tool calls) in the terminal. It’s handy for an agent to read what happened earlier: after a context compaction, in a fresh shard, or to review a sibling shard’s work. It defaults to the active shard like crystl screen.

Bare crystl history prints a navigation index: a session header, one line per row (sequence, time, kind, tool and status, and a one-line preview), and hints you can run to pull a row. Skim it, then fetch just the rows you want with --row <seq> (or --rows 47,51), which returns the whole body, and a tool call’s result along with it. The index also gives each row a durable rowRef; --ref fetches by that instead, and it stays correct after the shard switches sessions. Want the old dump of everything? That’s crystl history --all.

Narrow the index with --index --tool <name>, --index --status ok|error|pending, --tools-only, and --limit. (--tool and --status are index-only, so they want the explicit --index.) A tool call and its result count as one unit, so filtering and windowing never split a pair. --all can’t be narrowed by any of them: it means the whole transcript, and crystl asks you to pick rather than return less than that.

The session summary (total tokens, tool calls, models, wall-clock active time) still prints on top, so you can judge a session’s cost and context at a glance. Per-turn model, token usage, and duration aren’t on the index lines; they come back with the rows you fetch, with --all, and in --json.

--json is unchanged: it still returns the full response with every body and all the per-turn metadata (usage, model, stopReason, cwd, gitBranch), so scripts that read it keep working. --index --json returns the index envelope.

Remote sessions

For a remote (SSH) shard, the transcript lives on the remote host. crystl fetches it over the existing connection and reads it with the same navigator and CLI. No extra setup.

Session restore

Separately from the navigator, crystl restores your Claude sessions when you restart. The conversation context, approval state, and session position are preserved, so you pick up exactly where you left off, without re-explaining context. Guild members also get session restore when loading formations.

Restore on restart is currently available for Claude Code sessions; Codex and Antigravity shards open fresh when crystl restarts. Note this is different from resurrecting a closed shard (undo-close), which does reopen Codex (codex resume) and Antigravity (agy --conversation) conversations as well as Claude. Restart-restore just hasn’t been extended to them yet.

Global timeline search (Cmd+Shift+F)

Beyond the per-gem navigator, crystl keeps a timeline: its own searchable record of what every shard’s agent said and every shell command that ran, across all gems, all sessions, isolated worktrees, quests, and SSH shards. Unlike the navigator, the timeline is agent-neutral: Claude Code, Codex, Antigravity, and Kimi Code conversations all ingest, and plain shell shards are recorded too. Even an agent whose structured transcript the navigator can’t yet read still has its terminal output captured and searched here.

Press Cmd+Shift+F anywhere to search it. Results span open and closed shards; activating a hit jumps to the shard if it’s open, or shows the surrounding conversation read-only if it isn’t. Agents can open this palette for you too: crystl history show "<query>" --shard <name> pre-fills it, so an agent can show you a moment from history instead of quoting terminal text.

The same record powers crystl history search / metrics from the CLI and the bridge API, including per-model token and cost rollups.

What’s stored, and deleting it

The timeline lives in a single local SQLite database (~/.config/crystl/history.db) that indexes your transcripts and command history. It never leaves your machine and is never the source of truth. Deleting it loses nothing but the search index (it can always rebuild from the transcripts that remain).

What goes in: agent conversation turns (text capped at 4,000 characters per turn, since it’s a search index, not a second copy of your files) with each turn’s model and token usage, and every shell command with its directory, exit code, and timing. Ingest happens automatically (at launch, whenever an agent finishes a turn, and live as commands complete), so there’s nothing to manage.

Settings → Storage shows exactly what’s stored (with a per-gem breakdown) and offers scoped deletion: per gem, older-than a cutoff, or everything. Clearing is always safe for your work: it never touches your conversations, files, or projects; you only lose the ability to search that history in crystl, permanently. The same controls exist as crystl history clear.

Storage also shows the database’s size on disk, with a compact button beside it. SQLite doesn’t shrink a file when rows are deleted, so a clear on its own frees no disk space; compacting checkpoints and vacuums the database and reports the before and after sizes. It rewrites the file, so give it a moment on a large history. Nothing about your history changes identity, so any row reference an agent is holding still resolves. crystl history compact does the same thing from the CLI.