# contextburn

Reads the Claude transcripts already on your disk and reports what share of paid tokens turned into model output rather than context re-reading.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI
- Author: arsentev-ai
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/arsentev-ai/contextburn
- Updated: 2026-10-06
- HTML: https://affpapa.org/en/nevibecode/mcp/contextburn

## What it does

contextburn parses the session logs Claude leaves on your machine. What you get back is a share: how much of what you paid for came out as model output, and how much was the agent reading context it had already sent. A token counter tells you what you spent. This tells you how much of that was work.

There are two figures, and they behave differently. The token share barely moves between runs, since every agent step resends the accumulated context. The cost-weighted share does move, because cached reads are priced below fresh input and output, so it reflects how you run sessions. Per-model prices sit at the top of `bin/contextburn` and need updating by hand when they change.

The CLI is a single Python 3 file with no dependencies, copied into `~/bin`. The MCP server speaks stdio and exposes two tools: `run_efficiency` for the shares as structured data, `spend_breakdown` for the full report. Only local transcripts under `~/.claude/projects/**/*.jsonl` are read, and there are no network calls. Claude transcripts are the only source it handles for now, so there is nothing to count on other agents.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add contextburn -- uvx contextburn
```
uvx runs the command named after the package; if the README names another one, use uvx --from contextburn <command>

### Codex

**Platform CLI**
```bash
codex mcp add contextburn -- uvx contextburn
```
uvx runs the command named after the package; if the README names another one, use uvx --from contextburn <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "contextburn": {
            "command": "uvx",
            "args": [
                "contextburn"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from contextburn <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "contextburn": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "contextburn"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from contextburn <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add contextburn uvx contextburn
```
uvx runs the command named after the package; if the README names another one, use uvx --from contextburn <command>

## When to use it
- see what share of paid tokens became model output
- spot how much context the agent re-reads
- compare one long session against several short ones
- let the agent check its own run efficiency mid-session
- watch the current token burn rate

## Example prompts
- Show my run efficiency for the last 24 hours
- Break down what inflated the context in this session
- How many tokens went to re-reading versus output?

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 392262
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33989
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81163
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119231
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47577
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43902

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md