An Obsidian plugin for viewing Claude Code sessions. Browse, search, analyze, and export your Claude Code sessions as interactive timelines with live watch and rich tool rendering — right alongside your notes.
Warning
v0.2.2 — Desktop-only. Active development; expect frequent changes.
- All turns rendered in a scrollable timeline — no pagination, no lazy loading
- Collapsible turn headers with role labels (USER / CLAUDE) and colored left borders
- Progress bar with per-turn dots positioned by real timestamps
- Content filter menu: hierarchical toggles for User (text, images) and Assistant (text, thinking, tool calls, tool results)
Every tool type gets purpose-built rendering:
- Bash — syntax-highlighted code block with command description; diff detection for unified diff output
- Edit — red/green diff view (success messages hidden; errors shown)
- Write — syntax-highlighted code with language detection from file extension
- Read — language-specific syntax highlighting
- MCP tools — displayed as
server / tool_nameinstead of rawmcp__server__tool - Sub-agent sessions — inline with collapsible prompt, tool groups, and output
- Tool grouping — consecutive calls above a configurable threshold (default 4) collapse into a summary bar
- Hook indicators — fish icon with tooltip on hook-triggered tool calls
- Orphan detection — tool calls without results show "in progress" (last turn) or "interrupted" (mid-session)
- Tool result images rendered as clickable thumbnails with full-size modal
Collapsible panel at the top of each session:
- Hero cards — cost, context window, turns, and duration
- Token chart — stacked horizontal bar (cache read, cache write, uncached, output)
- Tool chart — horizontal bars sorted by invocation count
- Metadata grid — project, model, version, branch, start time, duration, working directory
- Session ID and Obsidian URI with copy buttons
- File watcher auto-reloads the session on JSONL changes
- UI state preserved across re-renders (expanded tools, scroll position, show-more, turn collapse)
- Optional pending tool notification — Obsidian Notice + system notification when a tool call is waiting for permission
- Configurable auto-scroll on update
Dual-mode search panel in the right sidebar:
- Cross-session — keyword search across all JSONL files with progressive results, newest first
- In-session — scoped to the active timeline with DOM highlighting
- Role filter (all / user / assistant), debounced input, arrow key navigation between results
- Scans configured directories for JSONL session files
- Cached session index — only new/modified files are re-read
- Empty sessions filtered automatically
- Fuzzy search by project name, path, or session ID
- Markdown — YAML frontmatter + Obsidian callouts
- HTML — self-contained, zero-dependency file with embedded CSS (captures your current theme), inline images, and standalone JS for all interactive features
Open sessions directly via protocol handler:
obsidian://claude-sessions?session=/path/to/session.jsonl&turn=7
Paths can use ~ for the home directory, e.g. obsidian://claude-sessions?session=~/.claude/projects/.../session.jsonl.
- Install the BRAT plugin
- Open BRAT settings → Add Beta plugin
- Enter:
gapmiss/claude-sessions - Enable the plugin under Settings → Community plugins
Copy main.js, styles.css, and manifest.json into:
<your-vault>/.obsidian/plugins/claude-sessions/
Restart Obsidian and enable the plugin under Settings → Community plugins.
git clone https://github.com/gapmiss/claude-sessions.git
cd claude-sessions
npm install
npm run build- Run the Claude Sessions: Browse sessions command (
Ctrl/Cmd+P) - The plugin scans your configured session directories for JSONL files
- Select a session from the fuzzy search modal
Run Claude Sessions: Import session file — drag-and-drop a .jsonl file, use the file picker, or paste a path.
With a session open, run Export session to Markdown or Export session to HTML.
| Command | Description |
|---|---|
| Browse sessions | Open a session from the fuzzy search modal |
| Search sessions | Open the cross-session search panel |
| Search in session | Search within the active session |
| Import session file | Open a session from file path or drag-and-drop |
| Export session to Markdown | Export as Markdown with frontmatter |
| Export session to HTML | Export as self-contained HTML |
| Expand all | Expand all collapsed turns |
| Collapse all | Collapse all turns |
| Refresh session | Re-read and re-render the current session |
| Toggle live watch | Start/stop watching the session file for changes |
| Setting | Default | Description |
|---|---|---|
| Session directories | ~/.claude/projects |
Directories to scan for JSONL files (supports ~) |
| Export folder | Claude sessions |
Vault folder for exported files |
| Show thinking blocks | On | Display thinking/reasoning blocks |
| Show tool calls | On | Display tool use blocks |
| Show tool results | On | Display tool result output |
| Show hook icons | On | Display hook indicators on tool calls |
| Tool group threshold | 4 | Consecutive tool calls above this collapse into a group |
| Auto-scroll on update | On | Scroll to bottom on live watch changes |
| Notify on pending tool | Off | System notification when a tool call awaits permission |
The Claude Code JSONL format stores each content block (text, thinking, tool_use) as a separate record. The parser:
- Merges consecutive assistant records into single logical turns
- Deduplicates streaming records by UUID (keeps the most complete version)
- Attaches tool results from user records to the preceding assistant turn
- Extracts token usage, deduplicated by message ID, then summed into session stats
- Resolves sub-agent sessions from
subagents/agent-<id>.jsonlfiles - Skips encrypted thinking blocks (Claude Code v2.1.79+) and non-content record types
The timeline view renders all turns immediately into a scrollable container. An IntersectionObserver drives scroll-based opacity. Tool-specific renderers handle Bash, Edit, Write, and Read with syntax highlighting and diff views.
npm install
npm run dev # watch mode with source maps
npm run build # typecheck + production bundle
npm test # 98 tests (vitest)
npm run test:watch # watch mode tests
npx eslint . # lint with eslint-plugin-obsidianmd- TypeScript 5.8 / esbuild
- diff for Edit tool rendering
- eslint-plugin-obsidianmd for Obsidian-specific linting
- Vitest for testing
- Obsidian API (desktop only — requires Node.js
fsaccess)