contextviz 0.1.0

Visualize local Claude Code session context

ContextViz

Visualize local Claude Code session context. Point it at ~/.claude/projects, open any session, and x-ray what fills the context window — system prompt, MCP instructions, skill listings, CLAUDE.md memory, conversation history, tool results, thinking, and images — with cache economics and actionable recommendations.

Status: Phase 4 complete — feature-complete. Adds the subagent explorer (the hidden cost of spawned Agent/Task runs — model, peak context, $ cost, tool count), the remaining recommendation rules (unused MCP, bulky CLAUDE.md, image cost, subagent spend), and live-tail: a "Go live" toggle that opens an SSE stream and refreshes the X-ray as the active transcript grows, following the newest turn.

Install

ContextViz runs entirely on your machine — it reads your local ~/.claude data and never sends it anywhere. Pick whichever is easiest:

Desktop app — download the installer for your OS from the latest release (.dmg / .exe / .AppImage / .deb). No Python or Node required.

Terminal — one-line install (downloads a dependency-free binary):

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/last-brain-cell/ContextViz/main/install/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/last-brain-cell/ContextViz/main/install/install.ps1 | iex

Terminal — PyPI (requires Python 3.11+):

pipx install contextviz   # or: pip install contextviz
contextviz

Any of these starts a local server and opens your browser. Override the data location with CLAUDE_HOME=/path/to/.claude.

A static landing page lives in site/ and deploys to GitHub Pages.

Architecture

• backend/ — FastAPI. Parses the JSONL transcripts and serves a JSON API.
• frontend/ — Vite + React + TypeScript + Tailwind v4 (visx + framer-motion for the viz).

The Vite dev server proxies /api → http://127.0.0.1:8000.

Run (dev)

Two terminals:

# 1) backend
cd backend
uv sync
uv run uvicorn app.main:app --reload --port 8000

# 2) frontend
cd frontend
npm install
npm run dev
# open http://localhost:5173

Override the data location with CLAUDE_HOME=/path/to/.claude for the backend.

API (so far)

• GET /api/health
• GET /api/ledger → global Impact Ledger (spend, $ saved, PRs shipped, $/PR, by-project, daily trend, priciest sessions)
• GET /api/projects → { projects: [...] }
• GET /api/projects/{id}/sessions → { sessions: [...] }
• GET /api/projects/{id}/security → leaked secrets + dangerous commands (risk score)
• GET /api/projects/{id}/errors → recurring errors clustered + the fix that worked
• GET /api/projects/{id}/pr/{number} → Feature/PR Autopsy (cost, span, sessions, files, errors, rabbit holes)
• GET /api/projects/{id}/memoization → cross-session re-read analysis (CLAUDE.md candidates)
• GET /api/projects/{id}/file-evolution/files · …/file-evolution?path= · …/file-evolution/diff → one file's full version history stitched across every session, + cross-session diff
• GET /api/projects/{id}/sessions/{sid} → session detail (per-turn usage = scrubber stops)
• GET /api/projects/{id}/sessions/{sid}/context?leaf={uuid} → the X-ray breakdown
• GET /api/projects/{id}/sessions/{sid}/economics → cost, $ saved, hit rate, per-turn waterfall
• GET /api/projects/{id}/sessions/{sid}/recommendations → ranked actionable cards
• GET /api/projects/{id}/sessions/{sid}/timeline → tool events, durations, rabbit holes
• GET /api/projects/{id}/sessions/{sid}/subagents → spawned-agent cost report
• GET /api/projects/{id}/sessions/{sid}/redundancy → re-fetched/duplicated context + carry cost
• GET /api/projects/{id}/sessions/{sid}/events → SSE stream for live-tail
• GET /api/projects/{id}/sessions/{sid}/filehistory → File Time Machine changeset
• GET …/filehistory/content?hash=&version= · …/filehistory/diff?hash=&from=&to=
• POST …/filehistory/restore {path, hash, version} → restore a version to disk (guarded)

File Time Machine

Claude backs up every file before editing it (~/.claude/file-history/<session>/<hash>@vN), and the transcript's file-history-snapshot lines map each real path to its backup hash. This reconstructs every file a session touched, every version, the exact unified diff at each step, and lets you restore any version to disk — recovering intermediate states git never saw (even files no longer present). Restore is guarded: the target must be a path the session actually tracked and the hash is re-derived server-side. See backend/app/core/filehistory.py. You can also download a whole session's changes as a git-style .patch (…/filehistory/patch).

File Evolution (backend/app/core/file_evolution.py) zooms this out across the project: pick any file and see every version Claude ever saved of it across all sessions, stitched into one chronological timeline (color-coded by session) with cross-session diffs — a file's complete AI-edit biography, independent of git.

Impact Ledger (founder view)

A global ROI/velocity dashboard (/ledger, backend/app/core/ledger.py): total AI spend, the $ prompt-caching saved, PRs shipped (from the transcript's pr-link records) with cost attributed per PR, spend by project, a daily spend trend, and a drilldown to the priciest sessions. A fast usage-only scan (no tokenization) of every session on the machine, cached by a global mtime signature. Includes a Budget & forecast panel (run-rate, projected month-end, spike alerts, pacing vs a budget you set) and links each shipped PR to its Autopsy.

Security & Secrets Radar / Error Intelligence / PR Autopsy

• Security Radar (core/security_scan.py): scans transcripts for secrets exposed to the model (curated key patterns + tightened high-entropy assignment rule, values masked) and dangerous commands (rm -rf, force-push, DROP DATABASE, curl|sh…), with a risk score and jump-to-session.
• Error Intelligence (core/error_intel.py): clusters recurring errors across sessions (normalized signatures) and shows the command that most often succeeded right after — your own bug→fix history.
• PR Autopsy (core/pr_autopsy.py): given a PR number, finds every session that worked toward it and reconstructs cost, calendar span, files changed, errors, and rabbit holes. Linked from the Ledger's shipped list (/pr/:projectId/:number).

Redundancy Radar

A novel one: it finds content you paid to carry more than once — a file Read again with no Edit/Write to it in between, or a non-Read tool returning byte-identical output — and prices each avoidable copy by its carry cost (tokens × input_price × (cache_write_mult + cache_read_mult × turns_it_stayed_resident)). Jump-to-turn chips link each re-fetch back to the scrubber. See backend/app/core/redundancy.py.

Memoization Advisor (cross-session)

Zooms the Radar out to the whole project: a fast single-pass scan (no full parse / no tiktoken) of every session aggregates which files Claude re-reads, ranked by session-spread — a file pulled fresh into many separate sessions pays a recurring read tax that a few lines in CLAUDE.md / a skill would eliminate. Cached by a signature of the sessions' mtimes. Lives on the project page; see backend/app/core/project_redundancy.py.

How the X-ray adds up

The headline total for a turn is exact: input + cache_creation + cache_read from message.usage. The per-category split is estimated (tiktoken over each message's text) and then reconciled so the categories sum exactly to that headline — the system-prompt/tools baseline absorbs the remainder. Confidence tiers (exact / derived / estimated) are surfaced in the UI; nothing estimated is shown as exact.

The implementation plan lives at ~/.claude/plans/i-want-to-build-peaceful-owl.md.