Query local Claude Code session efficiency and token-spend breakdowns through two MCP tools.
run_efficiency: returns structured shares of paid tokens that became model output versus context re-reading, over a look-back window, by tokens and cost-weighted.
spend_breakdown: returns a human-readable report with run efficiency, sessions, and what inflated the context.
Both tools accept an hours parameter from 0.1 to 720; defaults are 24 for run_efficiency and 12 for spend_breakdown.
Works from local Claude Code transcripts with no network calls.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@contextburn how much of today's token spend actually became model output?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
By Evgenii Arsentev, MD, PhD — creator of Arsminal; Founder & CEO, Dad4Kids and arsentev.ai · ORCID 0000-0002-9120-7298
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.
cp bin/contextburn ~/bin/contextburn && chmod +x ~/bin/contextburn # python3 only, no dependencies
contextburn detail 24Related MCP server: tokenchit
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).
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.
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.
command | what it shows |
| what is burning tokens right now |
| run efficiency, sessions, and what specifically inflated the context |
| the current 5-hour subscription window |
| machine-readable state (used by the menu-bar app) |
| raw JSON dump of the parsed sessions |
| run efficiency as JSON |
| start the MCP server |
setting | default | meaning |
|
| interface language: |
|
| hour your day starts — the daily total resets here |
|
| tokens/hour that turns the menu-bar counter yellow |
|
| 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.
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.
claude mcp add contextburn -- uvx contextburn mcpOr install it as a Claude Code plugin, which registers the same server:
/plugin marketplace add arsentev-ai/contextburn
/plugin install contextburn@contextburnVS Code-compatible editors (VSCodium, Cursor, Windsurf, Gitpod…) — Open VSX: arsentev-ai.contextburn. A status bar meter over the local CLI; source in editors/vscode.
Raycast — source in editors/raycast, Store submission pending.
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.
swiftc -O -o ContextBurn app/main.swiftSet CONTEXTBURN_BIN=/path/to/contextburn if the CLI is not in ~/bin or the usual Homebrew paths.
Claude Code transcripts only, for now.
The cost-weighted share is only as current as the price table in bin/contextburn.
Software DOI (all versions): 10.5281/zenodo.22712985. GitHub's "Cite this repository" button gives the
reference; metadata is in CITATION.cff.
Evgenii Arsentev, MD, PhD (Евгений Арсентьев) — creator of Arsminal; Founder & CEO of Dad4Kids and ArsentevAI; founder of ReelsZavod. Physician and medical scientist who builds AI-agent systems in production and publishes the measurements.
ORCID 0000-0002-9120-7298 · Wikidata Q141398931
Projects and publications
Arsminal: free terminal for AI agents, built as a messenger (DOI 10.5281/zenodo.24079643)
AI Content Engine Economics: 1,497 short videos in 101 days by AI agents vs. people (DOI 10.5281/zenodo.22802228)
Context economy of agent sessions, the U-curve of context clearing (DOI 10.5281/zenodo.22759217)
AI managers in a live company, case series (DOI 10.5281/zenodo.23926850, 10.5281/zenodo.23927437)
contextburn: open-source meter of agent-run cost
hireburn: open method for AI-assisted hiring cost (payrollburn series)
IETF Internet-Drafts: draft-arsentev-agent-run-metrics, draft-arsentev-llm-context-discovery
Participant, W3C Agent Conformance and Benchmarking Community Group
ReelsZavod: AI content factory for Russian-speaking businesses
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.
MIT — see LICENSE.
Share of paid tokens that became model output versus re-reading of context already sent, over the last N hours of local Claude Code sessions. Reported by tokens and cost-weighted.
Inputs: hours.
Human-readable breakdown of token spend over the last N hours: run efficiency, sessions, and what specifically inflated the context.
Inputs: hours.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 2 tools
Both tools report on token spend and efficiency over the last N hours, and spend_breakdown explicitly includes run efficiency, so their boundaries overlap. An agent could reasonably confuse which tool to call for a pure efficiency metric versus a full breakdown.
Both tools use snake_case with descriptive two-word noun phrases, which is a predictable and consistent convention. However, run_efficiency is slightly less standard as a noun than spend_breakdown, and neither follows a verb_noun action pattern.
Two tools is borderline thin for a server analyzing context burn. While each tool has a distinct output, the surface feels minimal and may lack supporting operations like listing sessions or filtering by project.
The tools cover efficiency metrics and a spend breakdown including sessions, but there is no tool to list sessions, drill into a specific session, or filter by project/model. Core reporting is present but not exhaustive, which could cause dead ends for deeper analysis.
Exact Claude API cost calc with real cache economics, plus a tiktoken-misuse scanner.
Small tools for agent builders: AI-writing tells, tools/list token cost, CLAUDE.md lint, and more.
Work journal for coding agents: worklogs, tasks, project state and costs across projects.
LLM API prices and AI agent cost estimates, verified daily. Read-only cost lookup tools.