contextburn

Purpose

contextburn reads the session logs Claude Code has already written on your machine and tells you what proportion of the tokens you paid for actually became model output, and what proportion was the agent re-reading context it had already sent.

An ordinary token counter answers "how much did I spend"; contextburn answers "how much of that was real work". It gives a normalized share, so it can be compared across sessions, across models, and across ways of working.

Why two numbers

By token count, the share barely changes. Because the agent re-sends the accumulated context at every step, repeated reads dominate no matter what you do — it describes the agent itself.

By cost weighting, the share does move, because cache reads are priced far below new input and output. It depends on how you run the session — it describes you.

The comparison mentioned above comes from a controlled experiment with an accompanying dataset and analysis script: "Clear Every Third Task: A Measured U-Curve in the Context Economy of Coding Agents". Real output is shown on the 36 run session logs behind the U-curve report, with nothing else on the machine. The video has DOI: 10.5281/zenodo.22713920. The runs themselves are public: Hugging Face (DOI 10.57967/hf/10366), Kaggle, OSF (DOI 10.17605/OSF.IO/5QTWY).

Main capabilities

• Reads local Claude Code session logs (~/.claude/projects/**/*.jsonl). No data leaves the machine — completely no network calls.
• Deduplicates usage records by message id and keeps the per-element maximum. During streaming runs, an early snapshot and a final record are written for the same call: counting both double-counts, while keeping only the first halves the output.
• Uses cost-weighted share by model price, with the price table stored at the top of bin/contextburn . Update it there when prices change.
• Provides language files, because environment variables are not passed to the menu bar app when it is launched from Finder:echo ru > ~/.config/contextburn/lang switches the language of the app and CLI.
• Lets the agent read its own operating efficiency mid-session. A dependency-free MCP server (stdio) is bundled with the package, providing two tools:run_efficiency returns the share as structured data,spend_breakdown returns the full report.
• It can also be installed as a Claude Code plugin, which registers the same server.

Editor extensions

• VS Code-compatible editors (VSCodium, Cursor, Windsurf, Gitpod, etc.) — Open VSX:arsentev-ai.contextburn. Provides a status bar meter on top of the local CLI; source is at editors/vscode.
• Raycast — source is at editors/raycast, store submission pending.

Menu bar app (macOS)

app/main.swift is a small status bar app. It polls contextburn --jsononce a minute and shows the current burn rate and an hourly chart; click a bar to see that hour's details.

If the CLI is not in ~/bin or the common Homebrew paths, set CONTEXTBURN_BIN=/path/to/contextburn.

Applicable scenarios and limitations

• Currently only supports Claude Code session logs.
• The freshness of the cost-weighted share depends only on the price table in bin/contextburn .

Other information

• Software DOI (all versions): 10.5281/zenodo.22712985. GitHub's "Cite this repository" button provides citation; metadata is in CITATION.cff .
• Author: Evgenii Arsentev — arsentev.ai · ORCID 0000-0002-9120-7298.
• The project was released as tokmon on day one, then renamed to avoid confusion with an unrelated tool of the same name;TOKMON_* Environment variables are still valid.
• License: MIT—see LICENSE.