contextburn
Run efficiency for coding agents: share of paid tokens that became output, not context re-reading.
Open source Open in the app JSON README (API)
About
Run efficiency for coding agents: share of paid tokens that became output, not context re-reading.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- ai.arsentev
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.1
- Last push
- 2026-09-11T23:08:47Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-09-11 19:05:32
- Updated
- 2026-09-11 19:05:32
- Origin id
ai.arsentev/contextburn
README
<p align="center"> <img src="https://raw.githubusercontent.com/arsentev-ai/contextburn/main/assets/readme/hero.svg" width="100%" alt="contextburn: real output over 24 hours — useful work 0.18% of tokens, context re-reading 98.4%, cost-weighted useful work 6.7%, one useful token costs 555 paid tokens"> </p> <p align="center"><a href="https://doi.org/10.5281/zenodo.22712985"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.22712985.svg" alt="DOI 10.5281/zenodo.22712985"></a></p> **contextburn** reads the transcripts Claude Code already writes on your machine and tells you what 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 ```bash cp bin/contextburn ~/bin/contextburn && chmod +x ~/bin/contextburn # python3 only, no dependencies contextburn detail 24 ``` ## Demo <p align="center"> <img src="https://raw.githubusercontent.com/arsentev-ai/contextburn/main/assets/readme/demo.gif" width="100%" alt="contextburn detail 72 over the 36 experiment runs: 168 sessions, useful work 1.44% of tokens, context re-reading 94.4%, cost-weighted 28.8%"> </p> 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](https://doi.org/10.5281/zenodo.22713920). The runs themselves are open: [Hugging Face](https://huggingface.co/datasets/arsentev-ai/context-ucurve-coding-agents) (DOI 10.57967/hf/10366) · [Kaggle](https://www.kaggle.com/datasets/arsentevai/context-u-curve-of-coding-agents-36-runs) · [OSF](https://osf.io/5qtwy/) (DOI 10.17605/OSF.IO/5QTWY). ## Why two numbers <p align="center"> <img src="https://raw.githubusercontent.com/arsentev-ai/contextburn/main/assets/readme/two-numbers.svg" width="100%" alt="Same 12 tasks, one long session versus twelve short, 3 runs each: token efficiency 1.11% vs 1.12%, no difference; cost-weighted efficiency 31.6% vs 24.6%, seven points apart"> </p> - **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](https://doi.org/10.5281/zenodo.22699668). ## 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 <hours>` | 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. ```bash claude mcp add contextburn -- uvx contextburn mcp ``` Or install it as a Claude Code plugin, which registers the same server: ```text /plugin marketplace add arsentev-ai/contextburn /plugin install contextburn@contextburn ``` <!-- mcp-name: ai.arsentev/contextburn --> <!-- mcp-name: io.github.arsentev-ai/contextburn --> ## Editor extensions - **VS Code-compatible editors (VSCodium, Cursor, Windsurf, Gitpod…)** — [Open VSX: arsentev-ai.contextburn](https://open-vsx.org/extension/arsentev-ai/contextburn). A status bar meter over the local CLI; source in [`editors/vscode`](editors/vscode). - **Raycast** — source in [`editors/raycast`](editors/raycast), Store submission pending. ## Menu-bar app (macOS) `app/main.swift` is a small status-bar app. It polls `contextburn --json` once a minute and shows the current burn rate with an hourly graph; click a bar to see that hour's breakdown. ```bash swiftc -O -o ContextBurn app/main.swift ``` Set `CONTEXTBURN_BIN=/path/to/contextburn` if the CLI is not in `~/bin` or the usual Homebrew paths. ## Limits - Claude Code transcripts only, for now. - The cost-weighted share is only as current as the price table in `bin/contextburn`. ## Citing Software DOI (all versions): [10.5281/zenodo.22712985](https://doi.org/10.5281/zenodo.22712985). GitHub's **"Cite this repository"** button gives the reference; metadata is in [`CITATION.cff`](CITATION.cff). ## Author Evgenii Arsentev — [arsentev.ai](https://arsentev.ai) · ORCID [0000-0002-9120-7298](https://orcid.org/0000-0002-9120-7298) This project was published as `tokmon` on its first day and renamed to avoid confusion with unrelated tools of that name; `TOKMON_*` environment variables still work. ## License MIT — see [LICENSE](LICENSE).