context-forensics-mcp

Forensic analysis of Claude Code sessions: where your tokens went, what it cost, and where to compact.

An MCP server that reads the JSONL transcripts Claude Code already writes to ~/.claude/projects/ and answers with exact numbers — no estimates where the transcript already recorded the truth, no API keys, no network.

Session baf896a6 — 13 MB transcript, analyzed in 95 ms
Turns:   527 assistant / 338 user / 0 sidechain
Models:  claude-fable-5-1 ×527
Tokens:  input 15,052 | cache read 213,344,398 | cache write 5m 0 / 1h 3,341,571 | output 2,604,644 (thinking 799,980)
Cost:    $250.5503 (pricing 2026-09-20)
Peak:    628,101 tokens at turn 863 (62.8% of window)
Top hogs:
  Read: ~1,229,048 tokens, 19 call(s), 96.3%
  Bash: ~29,437 tokens, 126 call(s), 2.3%
  mcp__plugin_playwright_playwright__browser_snapshot: ~4,968 tokens, 6 call(s), 0.4%
Findings:
  [high] Read result ~158223 tokens at turn 500 — file .../report-full.png
  [high] Read result ~129573 tokens at turn 471 — file .../decision-dialog.png
  [high] Read result ~118104 tokens at turn 509 — file .../evidence-sheet.png

That session spent $53 on cache reads alone and 96% of its tool output was 19 PNG screenshots read as base64. You would never see that from inside the session.

Why

Every agent session has a context window that fills up, a bill that grows, and tools that quietly return more than they should. Claude Code records all of it — model, usage buckets, cache hits, every tool call and result — but nothing reads it back. This server does, and hands the result to the agent itself, so it can inspect its own sessions and adjust.

Related MCP server: tokenscope

Install

Requires Node 20+.

Claude Code

claude mcp add context-forensics -- npx -y context-forensics-mcp

Claude Desktop / Cursor / any MCP client — add to your MCP config:

{
  "mcpServers": {
    "context-forensics": {
      "command": "npx",
      "args": ["-y", "context-forensics-mcp"]
    }
  }
}

Then ask: "Analyze my latest session", "What ate the context in session abc123?", "How much did the my-app project cost this month?"

CLI (no MCP client needed)

npx -p context-forensics-mcp context-forensics report latest
npx -p context-forensics-mcp context-forensics list my-project

Tools

Every tool returns { ok: true, summary, data } or { ok: false, error, hint }. summary is one line for humans; data is compact JSON for the agent.

session accepts a session id (uuid), an absolute .jsonl path inside the allowed roots, or "latest".

Compaction heuristics

Configuration

Pricing override example — bump one price and add a new model:

{
  "asOf": "2026-12-01",
  "models": {
    "claude-sonnet-5": { "input": 3, "output": 15 },
    "claude-new-model": { "input": 4, "cacheRead": 0.4, "cacheWrite5m": 5, "cacheWrite1h": 8, "output": 20, "contextWindow": 1000000 }
  }
}

Accuracy

• Exact: every token count in tokens, cost and diff_context_growth comes straight from the usage block Claude Code recorded per turn — input, cache read, cache creation split by 5-minute / 1-hour TTL, output, thinking.

• Approximate: per-tool and per-file sizes are measured in bytes of the serialized result and converted at 4 bytes/token. They are labelled approxTokens everywhere. For images this overstates real image tokens (base64 is large, image tokens are not).

• Pricing: bundled from Anthropic's pricing page, dated in pricingAsOf. Unknown models get cost: null for that model and are listed in unknownModels — never guessed.

• Context size at a turn = input + cacheRead + cacheCreate5m + cacheCreate1h. Sidechain (subagent) turns are counted but excluded from the growth timeline.

Privacy

Read-only. No network calls, no writes, no telemetry, no child_process. The only files it opens are .jsonl transcripts under the allowed roots. Nothing leaves your machine.

Development

npm install
npm test               # vitest, 59 tests
npm run test:coverage  # thresholds: 80% lines / 70% branches
npm run typecheck
npm run build
npm run dev            # run the stdio server from source

tests/fixtures/real-anonymized.jsonl is a real transcript with every string replaced by same-length filler and every path hashed (scripts/anonymize.ts). Structure and usage numbers are untouched, which is what the parser and cost tests need.

Layout: src/parser (streaming JSONL → typed turns) → src/analysis (pure functions) → src/server (MCP tools with Zod schemas). src/discovery finds and gates transcript files; src/pricing owns the price table.

License

MIT