contextviz 0.1.1

Visualize local Claude Code session context

ContextViz

X-ray your Claude Code context. Point ContextViz at your local ~/.claude/projects, open any session, and see exactly what fills the context window — system prompt, MCP instructions, skill listings, CLAUDE.md memory, conversation history, tool results, thinking, and images — reconciled to the exact per-turn token total, with cache economics and actionable recommendations.

Everything runs on your machine. ContextViz only reads your own ~/.claude data and never sends it anywhere.

Features

• Context X-ray — see the system prompt, MCP, skills, CLAUDE.md, history, tool results, thinking, and images, each reconciled to the exact per-turn total.
• Redundancy Radar — find content you paid to carry more than once, priced by its carry cost.
• File Time Machine — every version of every file a session touched: diff and restore states git never saw.
• Subagent explorer — the hidden cost of spawned Agent/Task runs: model, peak context, dollars, tool count.
• Cache economics — cost, dollars saved by prompt caching, hit rate, and a per-turn waterfall.
• Cross-project file graph — every file Claude touched across all sessions, visualized as a force-directed network.
• Live-tail — go live and watch the X-ray refresh as the active transcript grows.

How this differs from broad agent dashboards

Multi-agent dashboards browse and search sessions and total up cost across many tools. ContextViz goes the other way: it's a microscope for Claude Code specifically. Because it focuses on one agent, it can reconstruct things a breadth-first tool can't — the exact composition of each context window, the carry-cost of redundant content, and every intermediate file version Claude saved. Single-agent scope is the point: it's the deepest view into Claude Code there is.

Install

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. Builds are currently unsigned, so macOS Gatekeeper / Windows SmartScreen may warn on first launch — the terminal installs below avoid that.

Terminal — one-line install ✅ recommended — highest success rate (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

Homebrew (macOS, Apple Silicon):

brew tap last-brain-cell/tap
brew install --cask contextviz

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.

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.

Deep dives

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.

Redundancy Radar

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.

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 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).

License

MIT — see LICENSE.