Metadata-Version: 2.4
Name: contextviz
Version: 0.1.1
Summary: Visualize local Claude Code session context
Project-URL: Homepage, https://github.com/last-brain-cell/ContextViz
Author-email: Naad Dantale <naadkd@gmail.com>
License: MIT
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115
Requires-Dist: orjson>=3.10
Requires-Dist: pydantic>=2.7
Requires-Dist: tiktoken>=0.13.0
Requires-Dist: uvicorn[standard]>=0.30
Description-Content-Type: text/markdown

# ContextViz

[![PyPI](https://img.shields.io/pypi/v/contextviz)](https://pypi.org/project/contextviz/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![Release](https://img.shields.io/github/v/release/last-brain-cell/ContextViz)](https://github.com/last-brain-cell/ContextViz/releases/latest)

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

![ContextViz — the Context X-ray of a Claude Code session](site/shots/context-xray.png)

![Cross-project file graph — every file Claude touched across all sessions](site/shots/cross-project-graph.png)

## 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](https://github.com/last-brain-cell/ContextViz/releases/latest)
(`.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):

```bash
# 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):

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

**Terminal — PyPI** (requires Python 3.11+):

```bash
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/`](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:

```bash
# 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.

![Ranked recommendations alongside cache economics](site/shots/recommendations-cache.png)

## Deep dives

![Tool timeline and the cost of spawned subagents](site/shots/timeline-subagents.png)

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

![File Time Machine — every saved version of a file, with diff and restore](site/shots/file-time-machine.png)

### 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`.

![Redundancy Radar — content you paid to carry more than once, priced by carry cost](site/shots/redundancy-radar.png)

### 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**.

![Impact Ledger — spend, dollars saved, PRs shipped, and budget forecast](site/shots/dashboard-ledger.png)

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

![Project Insights — Security & Secrets Radar, Error Intelligence, Memoization Advisor](site/shots/project-insights.png)

## License

MIT — see [LICENSE](LICENSE).
