context-diff
git difffor 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.
About the author
Built by yubinkim444, who also makes Kay's Records — an app for iOS and Android.
If this project saved you time, giving the app a try is the nicest way to say thanks.
License
MIT © yubinkim444
Metadata
Release files for context-diff 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| context_diff-0.1.1.tar.gz | 8.0 kB | Without provenance | Details for context_diff-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| context_diff-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for context_diff-0.1.1-py3-none-any.whl |
Total release size: 17.0 kB
Release files / context_diff-0.1.1.tar.gz
| Download URL | context_diff-0.1.1.tar.gz |
|---|---|
| Size | 8.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9142643ddf0d88aaee607fdb907a4a7f37a3cdeb8876bc405e27de2a917d6e51
|
|
BLAKE2b-256 checksum How to use checksums |
56226737906d445bc6e603feaba13e8d50e1968efdb6e030c5a80e91d0a85f67
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Release files / context_diff-0.1.1-py3-none-any.whl
| Download URL | context_diff-0.1.1-py3-none-any.whl |
|---|---|
| Size | 9.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b6a9dcd117e8c0c13a189f0e60bbc1760611b07a19d086366fe6067628a952b3
|
|
BLAKE2b-256 checksum How to use checksums |
92e362a7d7349c704e7abaf1c3f9c296e6b05f9740af390feb68b0a9db55093c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Security for context-diff 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.