This MCP server lets an agent inspect local Claude Code session efficiency and spending over a chosen look-back window.
run_efficiency — returns structured token-level and cost-weighted shares of paid tokens that became model output vs. re-reading already-sent context, for the last N hours (default 24).
spend_breakdown — returns a human-readable report covering run efficiency, sessions, and what inflated context, for the last N hours (default 12).
Both tools take an optional hours parameter, from 0.1 to 720 hours.
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.
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: token-meter
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 — arsentev.ai · ORCID 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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| hours | No | Look-back window in hours. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose useful behavior: the data source (local Claude Code sessions), the aggregation basis (reported by tokens and cost-weighted), and the look-back scope. It does not state that it is a read-only computation or what the return shape looks like, which leaves gaps for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences with no filler, and the metric definition leads before the scope qualifier. It is tightly written, though the second sentence is slightly compressed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no annotations, so the description must carry everything. It conveys the metric and its weighting but does not describe the return format or what the caller receives, leaving a modest gap for a zero-annotation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the hours parameter (range, default 24) is already fully documented. The description's 'over the last N hours' adds no syntax or format detail beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description defines the specific metric being reported: the share of paid tokens that became model output versus re-reading context, scoped to local Claude Code sessions. It is more than a restatement of the name 'run_efficiency'. However, it never distinguishes itself from its sibling spend_breakdown, so an agent gets a clear purpose but no sibling routing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance, no conditions, and no mention of the sibling spend_breakdown. The agent is left to infer that this is a metric-style report versus a cost breakdown, purely from the description text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Human-readable breakdown of token spend over the last N hours: run efficiency, sessions, and what specifically inflated the context.
| Name | Required | Description | Default |
|---|---|---|---|
| hours | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the output is human-readable and time-windowed, implying a read-only reporting operation. It stops short of stating permissions, cost, or whether the window is inclusive — gaps that are modest but real for an annotation-free tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One efficient sentence with the output shape front-loaded after the resource. No filler, though the colon-list format lists features rather than prioritizing what the agent needs most.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, annotation-free read tool with no output schema, the description covers the purpose, window, and report contents adequately. It leaves open the return structure for a self-described 'human-readable' report and gives no hint about sibling selection, so it is viable but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter at 0% schema description coverage, but the description explains it semantically ('over the last N hours'), which is the single most useful thing to know. It omits the default (12), bounds (0.1–720), and what happens when hours is left unset, so it adds meaning without fully compensating.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (token spend) and scope (last N hours) plus the report's contents (run efficiency, sessions, context inflation). It is clear on its own, but it doesn't distinguish itself from the sibling run_efficiency — in fact it names 'run efficiency' as a component, which could make an agent wonder whether to call this or that sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use guidance and no routing between this tool and run_efficiency. Usage is only implied by the reporting-oriented framing; nothing tells the agent when this is the right call versus the sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.1run_efficiencyspend_breakdownScored 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.
Opinionated sprint tracker. Read/update tickets, sprints, velocity from Claude/Cursor/Zed.
Deterministic AI agent microtools, no accounts/API keys. fetch_extract: 98% token cut. 38 tools.
Agent Cost Allocator MCP — multi-tenant LLM cost attribution for chargeback billing. Companion to
