20/20 hindsight for your Claude Code sessions
Documentation · Releases · Changelog
Claude Hindsight transforms opaque AI coding sessions into crystal-clear insights. It parses the raw JSONL transcripts that Claude Code writes to disk and gives you a full-featured web dashboard, real-time streaming, and deep analytics — all from a single binary with zero external dependencies.
- Understand what happened — browse every tool call, thinking block, and assistant message in a two-panel inspector
- Spot problems fast — errors are highlighted, filterable, and linked to their source nodes
- Track costs — per-session and per-model token breakdowns with OpenTelemetry integration
- Visualize execution — interactive 3D force-directed graph shows how nodes relate
- Stay current — live SSE streaming as Claude works, automatic session discovery
- Works offline — everything runs locally, no data leaves your machine
brew tap codestz/tap
brew install claude-hindsightcargo install claude-hindsightDownload from GitHub Releases — available for macOS (Apple Silicon & Intel) and Linux (x86_64 & aarch64).
git clone https://github.com/Codestz/claude-hindsight
cd claude-hindsight
make build # builds frontend + Rust binary → target/release/claude-hindsightRequires Rust 1.75+ and Node.js 20+. Pre-built binaries have no runtime dependencies — the web dashboard is embedded in the binary.
claude-hindsight init # discover sessions & build index
claude-hindsight integrate # install Claude Code hooks for auto-indexing
claude-hindsight serve --open # launch the web dashboardThat's it. Open http://localhost:7227 and explore your sessions.
The dashboard is the primary interface. Start it with:
claude-hindsight serve # http://localhost:7227
claude-hindsight serve --open # auto-open browser
claude-hindsight serve --port 8080 # custom portDashboard — global overview with session activity sparkline, KPI cards (sessions, projects, cost, errors), top tools, cost by model, most accessed files, MCP server usage, and recent activity feed.
Session Inspector — two-panel resizable layout. Left panel shows a flat execution list with color-coded node types, tool names, file chips, and error indicators. Right panel shows full node detail: markdown rendering, syntax-highlighted code (TypeScript, Rust, Python, Go, Bash, HTML, CSS), diff views, image previews, and token usage.
3D Execution Graph — interactive force-directed visualization of the session's node hierarchy. Nodes are colored by type, sized by importance. Bloom post-processing, starfield background, click-to-inspect.
Project Views — per-project session lists, aggregated analytics, tool usage patterns.
Activity Timeline — real-time event feed from Claude Code hooks showing tool calls, errors, and session lifecycle events.
Live Streaming — SSE-powered real-time updates. Watch nodes appear as Claude works.
Install lifecycle hooks so Hindsight auto-indexes sessions in real time — no manual reindex needed:
claude-hindsight integrate # install hooks (interactive)
claude-hindsight integrate --all # install in all settings files
claude-hindsight integrate --otel # also enable OpenTelemetry telemetry
claude-hindsight integrate --status # check what's installed
claude-hindsight integrate --remove # uninstall hooksHooks capture: session start/end, tool use, prompt submit, subagent activity, permission requests, task completion, and more. All hooks run async — zero impact on Claude Code performance.
Enable OTLP telemetry for detailed token-level cost tracking:
claude-hindsight integrate --otel # writes env vars to Claude Code settings
claude-hindsight serve # OTLP receiver runs alongside the dashboardThe dashboard then shows per-model cost breakdown, input/output/cache token splits, and cost-per-turn overlays.
| Command | Description |
|---|---|
serve [--open] [--port N] |
Start the web dashboard (recommended) |
init |
Discover sessions and build the SQLite index |
integrate [--all|--remove|--status|--otel] |
Manage Claude Code lifecycle hooks |
reindex [--verbose] |
Sync index with disk, refresh analytics, fix project names |
list [--project X] [--errors] [--today] [--last N] |
List sessions with filters |
search <query> [--tool X] [--errors] |
Search session content |
show <id> [--dashboard] |
Open a session in TUI or web |
watch [--dashboard] |
Tail the active session live |
export <id> [--output file.html] |
Export session to HTML report |
config show|edit|reset|validate |
Manage configuration |
paths list|add|remove |
Manage scan directories |
clean [--db|--all] |
Reset database or full config |
For terminal-native workflows, Hindsight also includes a TUI:
claude-hindsight # launch TUI (default when no command given)
claude-hindsight show <session-id> # open specific session
claude-hindsight watch # watch active session liveNavigate with j/k, filter with /, switch focus with Tab, copy with y, quit with q.
Tip: For the best experience, use
claude-hindsight serve --openinstead. The web dashboard has richer visualizations, better navigation, and the 3D execution graph.
Claude Code CLI
│ writes JSONL transcripts
v
~/.claude/projects/
my-app/session-abc123.jsonl
│
v
Claude Hindsight
├── JSONL Parser (streaming, deduplicating)
├── Tree Builder (UUID-based parent/child hierarchy)
├── SQLite Indexer (O(1) lookups, aggregated analytics)
├── OTLP Receiver (token costs, model breakdown)
├── File Watcher (live updates via kqueue/inotify)
└── SSE Stream (real-time to browser)
│
├── Web Dashboard (axum + React, embedded in binary)
└── Terminal UI (ratatui)
- Session transcripts — Claude Code writes JSONL to
~/.claude/projects/. Each line is a node (message, tool call, result, thinking block, etc.) - Node hierarchy — Nodes link via
uuid/parent_uuidto form an execution tree - Smart labels — Nodes are categorized and color-coded: tool calls (amber), thinking (violet), errors (rose), subagents (emerald), tasks (sky)
- Embedded UI — The React dashboard is compiled into the binary at build time via
rust-embed. No Node.js needed at runtime. - Auto-update detection — After upgrading, Hindsight suggests running
reindexto refresh analytics. Checks GitHub for new versions once per day.
claude-hindsight config show # print current config
claude-hindsight config edit # open in $EDITOR
claude-hindsight config validate # check for errors
claude-hindsight config reset # restore defaultsConfig lives at ~/Library/Application Support/claude-hindsight/config.toml (macOS) or ~/.config/claude-hindsight/config.toml (Linux).
claude-hindsight paths list
claude-hindsight paths add ~/work/.claude/projects --name Work
claude-hindsight paths remove ~/old-projects| Layer | Technology |
|---|---|
| Core & CLI | Rust, clap |
| Web server | axum, tokio |
| Web frontend | React 19, Vite, react-force-graph-3d |
| Terminal UI | ratatui, crossterm |
| Database | SQLite (bundled via rusqlite) |
| Asset embedding | rust-embed |
| File watching | notify (kqueue/inotify) |
| Telemetry | OpenTelemetry (OTLP log receiver) |
The Homebrew tap was renamed from Codestz/homebrew-tap to codestz/tap. If you installed with the old tap, you will get errors on upgrade. To fix:
brew untap Codestz/homebrew-tap # remove the old tap
brew tap codestz/tap # add the new one
brew install claude-hindsight # reinstallIf you are unsure which tap you have:
brew tap # lists all tapsIf you see Codestz/homebrew-tap in the list, run the migration above.
Hindsight automatically detects version changes and suggests running reindex:
↑ Updated to v2.3.0 (was v2.2.0). Run hindsight reindex to refresh analytics and fix project names.
Just run claude-hindsight reindex — it syncs the index with disk, corrects project names, and refreshes all analytics.
claude-hindsight clean # delete the database
claude-hindsight init # rebuild from scratchNo data is lost — Hindsight re-parses the original JSONL files.
claude-hindsight serve --port 8080 # custom dashboard port
lsof -i :7227 # find what's using the default port- Use Claude Code at least once
- Run
claude-hindsight init - If sessions are in a non-default location:
claude-hindsight paths add /path/to/projects
See CONTRIBUTING.md for setup instructions and coding standards.
MIT — see LICENSE for details.
Made with care for the Claude Code community
Because every AI decision deserves 20/20 hindsight.
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}