🩺 CC Token Doctor — Why Your Claude Code Is Eating Tokens Like Pac-Man (And How to Fix It)

TL;DR: If you use Claude Code and your tokens have been disappearing way too fast since late March — you're not imagining it. There are actual bugs causing this, and I built a free tool to figure out what's hitting you and fix it.

The Problem (In Plain English)

Since around March 23rd 2026, something broke in Claude Code. People paying $100-200/month for Max subscriptions started burning through their entire session allowance in under 90 minutes. Some people hit 100% usage on a single message.

That's not normal. That's not "you're using it wrong." That's a bug.

Actually, it's three bugs stacked on top of each other, which is why it's been so confusing to figure out what's going on:

1. The cache stopped working properly Claude Code has a system where it remembers what it already read so it doesn't have to read it again every single time you send a message. Think of it like a bookmark — instead of re-reading the whole book from page one, it picks up where it left off. That bookmark system broke. So now it's re-reading the entire book on every single message, and charging you for it. That's 10-20x more expensive per message.

2. Peak hours throttling Anthropic quietly started making your tokens burn faster during busy hours (weekdays 5am-11am Pacific Time). If you're in Europe, that's your afternoon. They confirmed this, but didn't exactly shout about it.

3. The usage counter is lying Multiple people have reported their usage jumping from "30% used" to "100% used" on a single message. The meter itself is buggy.

Anthropic's official response: "We're aware. Investigating." No fix date.

What CC Token Doctor Does

It's a free, open-source tool that does three things:

1. Tells you what's actually wrong

Not a vague "something might be off." It scans your Claude Code sessions and gives you a clear answer: "Your cache is broken" or "You're working during peak hours" or "Both" or "Your usage is actually normal — Anthropic just reduced limits."

2. Shows you the numbers

Cache hit ratio (are your bookmarks working?), token usage per message (is anything spiking?), whether your sessions are resuming properly. All in plain English with colour-coded indicators.

3. Fixes it (if you want)

For each problem it finds, it offers a specific fix. Every fix explains what it does before it touches anything. You choose what to apply. Full backup created first, and you can undo everything with one command.

How to Use It

You need Node.js installed (if you're using Claude Code, you already have it).

Open your terminal and type:

npx cc-token-doctor

That's it. One command. No installation needed.

It will scan your sessions, show you what's wrong, and offer to fix it. The whole thing takes about 30 seconds.

If you want a visual dashboard with charts and colour-coded health indicators, there's a web version too at aidhd.co/token-doctor — just drop in the report file and it shows you everything in a nice visual layout.

Other useful commands:

npx cc-token-doctor --diagnose-only — just tell me what's wrong, don't fix anything
npx cc-token-doctor --undo — put everything back the way it was
npx cc-token-doctor --fix — apply all recommended fixes

Privacy

This was really important to me:

Everything stays on your machine. The tool runs locally, not in the cloud.
Nothing is uploaded anywhere. Not to me, not to anyone.
The web dashboard runs in your browser. Your data never leaves your computer.
It's fully open source. You can read every line of code before you run it.

GitHub: github.com/martusha89/cc-token-doctor

Why I Built This

Because I was pissed off, honestly. People paying for Claude Code, tokens are vanishing, and the only existing fixes were command-line scripts that assume you already know what a cache prefix is. Most people just want to know: is something broken, and can you fix it?

So that's what this does. No jargon. One command. Clear answers.

This tool stands on the shoulders of community researchers who figured out where the bugs are — especially Rangizingo, flightlesstux, and kitaekatt. I just made it accessible.

FAQ

Will this break my Claude Code? No. Every fix creates a full backup first, and you can undo everything with npx cc-token-doctor --undo.

What if Anthropic fixes the bugs? Great! Then the diagnostic will tell you "everything looks healthy" and there's nothing to fix. The monitoring features are still useful either way.

Do I need to be technical to use this? You need to be comfortable opening a terminal and typing one command. That's the bar.

Is this an official Anthropic tool? No. This is a community-built, open-source tool. Not affiliated with Anthropic.

If this helped you, star the repo on GitHub and share the post. The more visibility, the more pressure to get official fixes shipped.