Metadata-Version: 2.4
Name: contextviz
Version: 0.1.0
Summary: Visualize local Claude Code session context
Project-URL: Homepage, https://github.com/last-brain-cell/ContextViz
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

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](https://github.com/last-brain-cell/ContextViz/releases/latest)
(`.dmg` / `.exe` / `.AppImage` / `.deb`). No Python or Node required.

**Terminal — one-line install** (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
```

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

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