You start a refactor at 70% context. Halfway through, Claude forgets a constraint you set an hour ago.
See your Claude Code context before it runs out
context-stats puts free tokens, context zone, and model sharpness in your Claude Code status line. When a session ends, it tells you where the tokens and the money went.
- MIT licensed
- Zero dependencies
- Python 3.10+
- Runs entirely on your machine
my-project | main [3] | 64,000 free (32.0%)·Code·ᗤ | MI:0.918 | +2,500 | $0.42 | Opus 4.6·high | abc-123
Claude Code shows you the conversation, not the context window behind it.
Autocompact fires mid-task and the plan you agreed on is summarized away.
The monthly bill arrives and you cannot say which project or session drove it.
Model quality drops as the window fills, and nothing on screen tells you when.
- Work done late in a full session gets redone in a fresh one, so you pay for it twice.
- Past 150k tokens on 1M-context models, every turn moves into a higher cost tier.
- Sessions that never reuse the prompt cache keep paying full input price. Cache reads cost roughly 10x less.
context-stats reads what Claude Code already reports, keeps a local history, and gives you three levels of answers.
Live
A status line with free tokens, a color-coded context zone, session cost, and an optional Model Intelligence score, refreshed on every turn.
Session
context-stats export writes a Markdown deep-dive: cache reuse, interaction timeline, and zone history for one session.
Report
context-stats report totals spend, cache hit ratio, and cost per project across every session, for any number of days.
Context zones
- Planningplenty of room, keep planning and coding.
- Pricingcost tier increases, consider /compact.
- Code-onlyfinish the current task, no new plans.
- Dumpquality declining, wrap up.
- ExDumpnear the hard limit, start a new session.
- Deadstop.
Model Intelligence
MI(u) = max(0, 1 − u^β)
Calibrated from the MRCR v2 8-needle benchmark. Opus 4.6 scores 0.713 at 50% full and 0.404 at 75%.
No telemetry, no account, no runtime dependencies. Session data stays in ~/.claude/statusline/ on your machine. The only network call is the optional gh PR lookup (show_pr=false turns it off).
How it works
Install the package:
pip install context-statsWire it into Claude Code:
context-stats doctor --fixRestart Claude Code. The status line appears on the next turn.
Social proof
“[proof needed — testimonial from a Claude Code user]”
Example usage report, 30 days
- total spend
- $6,413.24
- sessions
- 764
- projects
- 58
- cache hit ratio
- 46.9%
- average session cost
- $8.39
FAQ
Is it free?
Yes. context-stats is MIT licensed and has zero runtime dependencies.
Does it send my data anywhere?
No. Session data stays in ~/.claude/statusline/, and reports aggregate those same local state files. The optional PR number is looked up through your local gh CLI, which contacts GitHub (show_pr=false turns it off).
What do I need to run it?
Python 3.10 or newer and Claude Code. The full multi-line layout needs Claude Code v2.1.153 or newer.
I installed it but no status line appears. What now?
Run context-stats doctor. It checks the entry points, a sandboxed render, the settings.json wiring, and the state directory, then prints the exact fix.
Can I hide parts of the status line?
Yes. Each element has a toggle in ~/.claude/statusline.conf, such as show_cost=false or show_delta=false, and accepts 18 named colors or any #rrggbb hex.
Does it slow Claude Code down?
Git commands run with a 5-second timeout, and the branch and PR number are cached between refreshes.
Know your context zone before Claude does.
Free and open source. No account, no sign-up, no telemetry.