contextburn

What it does

contextburn reads the transcripts a language-model coding agent already writes on the local machine and reports what share of the paid tokens actually became model output — and how much was the agent re-reading context it had already sent.

Token counters answer "how much did I spend?". contextburn answers "how much of it was work?" — as a normalised share, so runs can be compared across sessions, models and ways of working.

Two numbers

• By tokens the share barely moves: every agent step resends the accumulated context, so re-reading dominates. It describes the agent.
• Cost-weighted the share does move, because cached reads are priced far below fresh input and output. It describes how you run your sessions.

How it counts

• Reads local agent 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, so a streaming runtime's early snapshot and final record for the same call are not double-counted.
• Weights the cost share with per-model prices kept in the script, so they can be updated when prices change.

Install and run

pip install contextburn
contextburn detail 24

Python 3 only, no dependencies. MIT licence.

Cite

Arsentev, E. contextburn: a run-efficiency meter for language-model coding agents. DOI: 10.5281/zenodo.22712985

The measurement behind it: Clear Every Third Task: A Measured U-Curve in the Context Economy of Coding Agents, DOI: 10.5281/zenodo.22699668

More: https://arsentev.ai · https://arsentev.ai/research