Metadata-Version: 2.4
Name: context-diff
Version: 0.1.0
Summary: See what blew up your Claude Code context window — git diff for token usage.
Project-URL: Homepage, https://github.com/yubinkim444/context-diff
Project-URL: Repository, https://github.com/yubinkim444/context-diff
Project-URL: Issues, https://github.com/yubinkim444/context-diff/issues
Author: yubinkim444
License-Expression: MIT
License-File: LICENSE
Keywords: claude-code,context-window,debugging,developer-tools,llm,tokens
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.10
Description-Content-Type: text/markdown

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

[![PyPI](https://img.shields.io/pypi/v/context-diff)](https://pypi.org/project/context-diff/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)]()
[![License: MIT](https://img.shields.io/badge/license-MIT-green)]()

---

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

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

Zero dependencies. Pure Python ≥3.10.

---

## Use

```bash
# 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?"**
```bash
context-diff --auto --top 10
```

**"Which tool calls in my project are consistently expensive?"**
```bash
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."**
```bash
diff <(context-diff a.jsonl --no-color) <(context-diff b.jsonl --no-color)
```

---

## Companion projects

- **[mcp-rec](https://github.com/yubinkim444/mcp-rec)** — VCR for MCP servers.
- **[llm-cache-proxy](https://github.com/yubinkim444/llm-cache-proxy)** — disk cache for OpenAI/Anthropic API calls.
- **[promptlock](https://github.com/yubinkim444/promptlock)** — lockfile for your prompts.

---

## License

MIT © yubinkim444
