The Problem Everyone Had

Here's the thing about Claude Code on a Pro or Max subscription. You're paying a flat monthly fee. Anthropic tells you there's a usage cap but won't say exactly where the line is. Your only feedback mechanism is hitting the wall mid-conversation and getting rate-limited into oblivion for a few hours. No warning. No "you're at 80% of your budget." Just a brick wall and a suggestion to come back later.

So you either fly blind or you go digging through your local .jsonl session files trying to figure out how many tokens you burned today. And those files are not exactly bedtime reading.

ccusage fixes this. Properly.

What It Does

ccusage is a TypeScript CLI tool by ryoppippi that parses the JSONL session logs Claude Code writes to your local machine and turns them into formatted usage reports. Install it, run it, get a breakdown of exactly where your tokens went.

npx ccusage@latest

That's it. No config file. No API keys. No account setup. It reads your local session files and prints the numbers.

The output gives you:

Daily view showing token counts and costs per day. Good for spotting the day you accidentally left an agent running in a loop and burned through half your weekly budget in four hours.

Monthly view for the bigger picture. Are you trending up or down? Did that new project double your usage?

Session view breaking it down by individual Claude Code session. Handy when you're running multiple sessions and want to know which one is the expensive one.

5-hour billing window view that aligns with Anthropic's actual rate limit windows. This is the one that matters most for Pro/Max users because Anthropic's caps reset on 5-hour boundaries. If you're trying to pace yourself to avoid hitting limits, this is the view that tells you where you stand.

Per-model breakdown splitting Opus from Sonnet usage. Opus burns through your cap roughly 5x faster than Sonnet on the same task, so knowing your Opus-to-Sonnet ratio is the difference between "comfortable headroom" and "rate-limited at 2pm."

Why 12,000 People Starred This Thing

Because everyone had the same problem. 12,300 stars and 454 forks for a CLI that reads log files and does maths. That should tell you something about how badly the ecosystem needed this.

The alternatives at the time were: open the Anthropic dashboard (laggy, incomplete, doesn't show individual session data), build your own parser (life's too short), or just accept the mystery and deal with the rate limits when they hit. None of those are great options when you're paying for a subscription and want to know what you're getting for it.

ccusage also supports JSON export for piping into other tools, MCP server integration if you want your agent to check its own usage mid-session (yes, really, the agent can monitor its own burn rate), and multi-project tracking if you're running Claude Code across different repos.

📚 Geek Corner

The 5-hour window matters more than you think. Anthropic's rate limits for Pro and Max subscriptions operate on rolling 5-hour windows, not daily or monthly quotas. This means your usage pattern within those windows determines whether you get rate-limited, not your total monthly spend. ccusage's 5-hour window view is the only tool I've seen that aligns directly with this billing mechanic. If you're doing heavy work (say, running parallel agents or doing large refactors with Opus), check your 5-hour window before kicking off the next big task. Two hours of headroom feels safe until you realise your last three sessions ate 70% of the window.

The Competition

There's also Claude Code Usage Monitor by Maciek at roboblog, which takes a different angle. Instead of historical reports, it shows real-time terminal dashboards with live token burn rates, visual progress bars, and ML-based depletion predictions. It tells you when you'll hit your limit before it happens, not just where you've been.

Different tools for different needs. ccusage is your accountant looking at the books. Usage Monitor is your fuel gauge on the dashboard.

I run ccusage. The historical data is more useful for my workflow because I want to know which projects and sessions are expensive, not just whether I'm about to hit a wall right now. But if you're the type who runs hot and needs live feedback, Usage Monitor's the one.

Getting Started

npx ccusage@latest

It reads from the default Claude Code session directory on your machine. If you've used Claude Code even once, you've already got the data it needs. Just run it and see where your tokens went.