I blew through my weekly Claude Code quota in 2 days. No warning, no breakdown, no idea which sessions did it. So I dug into how Claude Code actually bills tokens - and built a free CLI to make it visible.
The quadratic cost problem
Claude Code re-sends the entire conversation history and all tool schemas on every single turn. That means:
- Turn 1 costs 1 unit of input tokens
- Turn 50 costs ~50 units
- A 100-turn session costs roughly 4x a 50-turn session, not 2x
Your costs grow quadratically with session length, and nothing in the UI tells you this.
Where the data lives
Claude Code writes every session as JSONL to:
~/.claude/projects//.jsonl
Each line contains token usage: input, output, cache writes, cache reads. All the data you need is already on your machine - there's just no tool to read it.
Enter agentburn
I built agentburn, a zero-dependency CLI that parses those files locally:
npx agentburn-cli
You get a per-session report: token summary with costs, a "burn curve" sparkline showing cumulative growth per turn, the top token sinks (exact tool calls that cost most), and "fat files" that get repeatedly read.
The doctor command
npx agentburn-cli doctor
This scans for waste patterns and gives concrete fixes:
- A file read 3 times costing 32k tokens? Add it to .claudeignore.
- 77% cache miss rate? Stop using --resume across days - prompt caches expire after ~1 hour.
- One Bash call eating 87k tokens? Split large operations.
Practical tips to lower your bill
- Keep sessions short. Because of quadratic growth, two 50-turn sessions are much cheaper than one 100-turn session.
- Don't let Claude re-read big files. Repeated reads of the same file are pure waste.
- Mind the cache. Prompt caches expire after about an hour - resuming an old session pays full price for the entire history.
- Measure. You can't optimize what you can't see.
It's open source
MIT licensed, zero dependencies, 100% local - your transcripts never leave your machine. If it's useful, a star on GitHub helps others find it.
Feedback and PRs welcome - especially for supporting Codex CLI and Gemini CLI transcript formats.
Top comments (1)
The tool-schema half of this deserves its own callout, because unlike history length it is something you control before the session even starts. Claude Code re-sends every registered tool's schema on every turn, so your fixed per-turn cost scales with how many MCP servers and tools are loaded. A 40-tool config carries that tax on turn 1 and turn 80 alike (cheaper on a cache hit, but never free), and it multiplies against the quadratic curve you plotted. Trimming to the servers a task actually needs, or lazy-loading them, shrinks the constant the quadratic keeps multiplying.
The other lever agentburn's doctor could surface: a subagent runs in its own context window, so pushing a heavy file-read or search subtask into a subagent keeps those tokens out of the parent transcript instead of letting them compound on every later turn. "This tool schema cost X across N turns" would make MCP bloat legible the same way you made repeated file reads legible.