context-diff 0.1.0

See what blew up your Claude Code context window — git diff for token usage.

context-diff

git diff for your Claude Code context window. See exactly which tool call ate 40k tokens, which turn evicted the cache, and how close you are to hitting the 200k ceiling.

---

Why

Your Claude Code session keeps hitting "auto-compact triggered." You suspect some tool result is huge — but which? Was it the 80-file find, the Read on the giant log, or the third agent you spawned in parallel?

context-diff reads your session JSONL (Claude Code records every turn locally) and renders a turn-by-turn token waterfall: input tokens, cache reads, deltas, which tool calls fired, and the top-N biggest jumps.

You go from "my context is full and I don't know why" to "Turn 14's Grep returned 38k tokens — I should have piped it through head" in 2 seconds.

---

Install

pip install context-diff
# or
uvx context-diff --auto

Zero dependencies. Pure Python ≥3.10.

---

Use

# Auto-pick the most recently modified session
context-diff --auto

# Or point at a specific session
context-diff ~/.claude/projects/-Users-you-proj/abc-def.jsonl

# Show top 10 biggest turns
context-diff --auto --top 10

# Machine-readable
context-diff --auto --json | jq '.[] | select(.delta_input > 10000)'

---

Example output

Turn  Kind          Δ tokens         in   cache_r  Label
─────────────────────────────────────────────────────────────────
   1  user                 —          —         —  user: fix the auth bug in /login
   2  assistant        1.2k        1.2k         —  ⬆ Read, Grep
   3  tool_result          —          —         —  ↳ tool_result × 2  (8,420 chars)
   4  assistant        2.1k        850       1.2k  ⬆ Edit
   5  tool_result          —          —         —  ↳ tool_result × 1  (320 chars)
   6  assistant       38.4k        420      38.0k  ⬆ Bash  ← BIG
   ...

Final context: 84.2k tokens (fresh=1.4k, cache_r=82.8k, cache_w=0)
Cumulative cache hit rate: 92.4%

Top 5 context-eating turns:
  1. Turn   6   38.4k tokens   ⬆ Bash
  2. Turn  12   12.1k tokens   ⬆ Grep
  3. Turn   4    2.1k tokens   ⬆ Edit
  4. Turn  18    1.4k tokens   ⬆ Read
  5. Turn   2    1.2k tokens   ⬆ Read, Grep

Red ← BIG markers highlight any turn that added more than 20k tokens. Yellow flags ≥5k.

---

What the columns mean

Column	Meaning
Δ tokens	Change in total context input vs. previous assistant turn. The number that tells you "this tool call cost me 38k tokens."
in	Fresh (uncached) input tokens — these are the ones you actually paid full price for.
cache_r	Tokens read from the prompt cache — these are ~10× cheaper.
Label	Tool calls issued (⬆) or tool results received (↳).

---

Where Claude Code stores sessions

OS	Path
macOS	~/.claude/projects/<encoded-cwd>/<uuid>.jsonl
Linux	~/.claude/projects/<encoded-cwd>/<uuid>.jsonl
Windows	%USERPROFILE%\.claude\projects\<encoded-cwd>\<uuid>.jsonl

--auto picks the most recently modified one across all projects.

---

Workflow recipes

"Why did my agent auto-compact at turn 30?"

context-diff --auto --top 10

"Which tool calls in my project are consistently expensive?"

for f in ~/.claude/projects/-Users-me-myproj/*.jsonl; do
  context-diff --no-color "$f" --json
done | jq -s '[.[][] | select(.kind=="assistant" and .delta_input > 5000) | .label] | group_by(.) | map({label: .[0], n: length}) | sort_by(-.n)'

"Compare two sessions side-by-side."

diff <(context-diff a.jsonl --no-color) <(context-diff b.jsonl --no-color)

---

Companion projects

• mcp-rec — VCR for MCP servers.
• llm-cache-proxy — disk cache for OpenAI/Anthropic API calls.
• promptlock — lockfile for your prompts.

---

License

MIT © yubinkim444