{ "markdown": "

\n \"contextburn:\n

\n\n

\"DOI

\n\n**contextburn** reads the transcripts Claude Code already writes on your machine and tells you what\nshare of the tokens you paid for became model output — and how much was the agent re-reading\ncontext it had already sent.\n\nToken counters answer *\"how much did I spend?\"*. This answers *\"how much of it was work?\"* — a\nnormalised share, so it can be compared across sessions, models and ways of working.\n\n## Try it\n\n```bash\ncp bin/contextburn ~/bin/contextburn && chmod +x ~/bin/contextburn # python3 only, no dependencies\ncontextburn detail 24\n```\n\n## Demo\n\n

\n \"contextburn\n

\n\nReal 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).\n\n## Why two numbers\n\n

\n \"Same\n

\n\n- **By tokens** the share barely moves. Every agent step resends the accumulated context, so\n re-reading dominates whatever you do — it describes the agent.\n- **Cost-weighted** the share does move, because cached reads are priced far below fresh input and\n output. It depends on how you run sessions — it describes you.\n\nThe comparison above comes from a controlled experiment with its dataset and analysis scripts:\n[Clear Every Third Task: A Measured U-Curve in the Context Economy of Coding Agents](https://doi.org/10.5281/zenodo.22699668).\n\n## How it counts\n\n- Reads local Claude Code transcripts (`~/.claude/projects/**/*.jsonl`). **Nothing leaves the\n machine — no network calls at all.**\n- Deduplicates usage records by message id and keeps the element-wise maximum. A streaming runtime\n writes an early snapshot and a final record for the same call: counting both double-counts it,\n keeping only the first halves the output.\n- Weights the cost share with per-model prices kept at the top of `bin/contextburn`. Update them\n there when they change.\n\n## Commands\n\n| command | what it shows |\n|---|---|\n| `contextburn` | what is burning tokens right now |\n| `contextburn detail [hours]` | run efficiency, sessions, and what specifically inflated the context |\n| `contextburn window` | the current 5-hour subscription window |\n| `contextburn --json` | machine-readable state (used by the menu-bar app) |\n| `contextburn --probe ` | raw JSON dump of the parsed sessions |\n| `contextburn --efficiency [hours]` | run efficiency as JSON |\n| `contextburn mcp` | start the MCP server |\n\n### Configuration\n\n| setting | default | meaning |\n|---|---|---|\n| `CONTEXTBURN_LANG` or `~/.config/contextburn/lang` | `en` | interface language: `en` or `ru` |\n| `CONTEXTBURN_DAY_START` | `6` | hour your day starts — the daily total resets here |\n| `CONTEXTBURN_WARN` | `30000000` | tokens/hour that turns the menu-bar counter yellow |\n| `CONTEXTBURN_ALARM` | `90000000` | tokens/hour that turns it red |\n\nThe language file exists because the menu-bar app is launched from Finder, where environment\nvariables never reach it: `echo ru > ~/.config/contextburn/lang` switches both the app and the CLI.\n\n## MCP server\n\nLet the agent read its own run efficiency mid-session. The package ships a dependency-free MCP\nserver (stdio) with two tools: `run_efficiency` returns the shares as structured data, and\n`spend_breakdown` returns the full report.\n\n```bash\nclaude mcp add contextburn -- uvx contextburn mcp\n```\n\nOr install it as a Claude Code plugin, which registers the same server:\n\n```text\n/plugin marketplace add arsentev-ai/contextburn\n/plugin install contextburn@contextburn\n```\n\n\n\n\n## Editor extensions\n\n- **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).\n- **Raycast** — source in [`editors/raycast`](editors/raycast), Store submission pending.\n\n## Menu-bar app (macOS)\n\n`app/main.swift` is a small status-bar app. It polls `contextburn --json` once a minute and shows the\ncurrent burn rate with an hourly graph; click a bar to see that hour's breakdown.\n\n```bash\nswiftc -O -o ContextBurn app/main.swift\n```\n\nSet `CONTEXTBURN_BIN=/path/to/contextburn` if the CLI is not in `~/bin` or the usual Homebrew paths.\n\n## Limits\n\n- Claude Code transcripts only, for now.\n- The cost-weighted share is only as current as the price table in `bin/contextburn`.\n\n## Citing\n\nSoftware DOI (all versions): [10.5281/zenodo.22712985](https://doi.org/10.5281/zenodo.22712985). GitHub's **\"Cite this repository\"** button gives the\nreference; metadata is in [`CITATION.cff`](CITATION.cff).\n\n## Author\n\nEvgenii Arsentev — [arsentev.ai](https://arsentev.ai) ·\nORCID [0000-0002-9120-7298](https://orcid.org/0000-0002-9120-7298)\n\nThis project was published as `tokmon` on its first day and renamed to avoid confusion with\nunrelated tools of that name; `TOKMON_*` environment variables still work.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n", "bytes": 6379, "sha": "aa1440b94bc530c3d89fd742f74d9e879b05ab6931b819f2aaae52d0e1784faf", "repo_slug": "arsentev-ai/contextburn", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_ai_arsentev_contextburn_82775be2/readme" }