arsentev-ai/contextburn

share of the tokens you paid for became model output — and how much was the agent re-reading
context it had already sent.
Token counters answer *"how much did I spend?"*. This answers *"how much of it was work?"* — a
normalised share, so it can be compared across sessions, models and ways of working.
Try it
Demo
Real output over the session logs of the 36 runs behind the U-curve report — nothing else on the machine. Video with DOI: 10.5281/zenodo.22713920. The runs themselves are open: Hugging Face (DOI 10.57967/hf/10366) · Kaggle · OSF (DOI 10.17605/OSF.IO/5QTWY).
Why two numbers
- **By tokens** the share barely moves. Every agent step resends the accumulated context, so
re-reading dominates whatever you do — it describes the agent.
- **Cost-weighted** the share does move, because cached reads are priced far below fresh input and
output. It depends on how you run sessions — it describes you.
The comparison above comes from a controlled experiment with its dataset and analysis scripts:
Clear Every Third Task: A Measured U-Curve in the Context Economy of Coding Agents.
How it counts
- Reads local Claude Code transcripts (~/.claude/projects/**/*.jsonl). **Nothing leaves the
machine — no network calls at all.**
- Deduplicates usage records by message id and keeps the element-wise maximum. A streaming runtime
writes an early snapshot and a final record for the same call: counting both double-counts it,
keeping only the first halves the output.
- Weights the cost share with per-model prices kept at the top of bin/contextburn. Update them
there when they change.
Commands
| command | what it shows |
|---|---|
| contextburn | what is burning tokens right now |
| contextburn detail [hours] | run efficiency, sessions, and what specifically inflated the context |
| contextburn window | the current 5-hour subscription window |
| contextburn --json | machine-readable state (used by the menu-bar app) |
| contextburn --probe | raw JSON dump of the parsed sessions |
| contextburn --efficiency [hours] | run efficiency as JSON |
| contextburn mcp | start the MCP server |
Configuration
| setting | default | meaning |
|---|---|---|
| CONTEXTBURN_LANG or ~/.config/contextburn/lang | en | interface language: en or ru |
| CONTEXTBURN_DAY_START | 6 | hour your day starts — the daily total resets here |
| CONTEXTBURN_WARN | 30000000 | tokens/hour that turns the menu-bar counter yellow |
| CONTEXTBURN_ALARM | 90000000 | tokens/hour that turns it red |
The language file exists because the menu-bar app is launched from Finder, where environment
variables never reach it: echo ru > ~/.config/contextburn/lang switches both the app and the CLI.
MCP server
Let the agent read its own run efficiency mid-session. The package ships a dependency-free MCP
server (stdio) with two tools: run_efficiency returns the shares as structured data, and
spend_breakdown returns the full report.