Watch the 5-hour block burn, not just the session total
Claude Code writes every session to plaintext JSONL under ~/.claude/projects/, and the community tool ccusage parses those files locally into daily/monthly/session reports and a live 5-hour-block dashboard — no API key, nothing leaving the machine.
The official documentation describes the mechanism this relies on. The technique itself is community practice.
What this costs you if it is wrong
ccusage's dollar figures are locally computed API-list-price equivalents, not your bill: on a subscription you pay a flat fee, so the number only proxies how hard you lean on the plan. Worse, this npx-es a third-party package pointed at your transcript directory, which the docs call unencrypted plaintext capturing any credential a tool read or a command printed. Pin a version you have read before running it on a machine whose sessions touched secrets. The first-party statusline rate_limits.five_hour field answers "am I about to hit the cap" with the server's own number.
You kicked off a long agentic run an hour ago. It is still going. The question you actually want answered is not "what did this session cost" — it is "at this rate, will I still have a plan left this evening?" /usage answers the first question well and the second one only in coarse bars, and neither /usage nor the session cost line is designed to sit open in a second pane while you work.
There are four different things people reach for here, and they are not substitutes for one another.
| What | Where it comes from | Answers | Costs |
|---|---|---|---|
/usage Session block | live token counts, priced locally at list price | "what has this session used, by model" | free, but resets on /clear |
/usage plan bars | server-side plan limits, d/w toggle for 24h vs 7d | "how much of my allowance is gone" | free, needs a subscription plan |
Status line rate_limits.five_hour | the server's own rolling-window number | "how close is the current 5-hour window to full, and when does it reset" | free, always visible, Pro/Max only |
ccusage (third party) | parses the local JSONL transcripts | day-over-day history, per-project and per-model splits, a live block view | an npx of someone else's package |
The mechanism the docs do confirm
Claude Code writes every session to a plaintext JSONL file under ~/.claude/projects/ — "every message, tool call, and tool result", in the docs' words — and keeps it for cleanupPeriodDays, 30 days by default. That is the substrate the tip rests on: the raw history of everything you have ever run is already sitting on your disk in a machine-readable format, whether or not you ever read it.
The docs also confirm the window this is about. The status line receives a rate_limits object with five_hour.used_percentage and five_hour.resets_at (Unix epoch seconds), plus the same pair for seven_day. Both fields appear only for Claude.ai Pro and Max subscribers and only after the first API response in the session, and Claude Code drops a window once its resets_at passes — so any script reading them has to handle absence:
FIVE_H=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')What ccusage adds, and what the candidate overstated
The claim is that ccusage daily, ccusage monthly, ccusage session, and ccusage blocks --live read those same transcripts and turn them into reports, with an --offline mode and a statusline subcommand that feeds a Claude Code status line. The genuinely useful part is not running it once out of curiosity — it is leaving a live view open in a second pane during a long run, so you learn you are burning the week's cap in an afternoon while you can still stop.
Two things in the original pitch do not survive contact with the docs, and you should know that before you install anything:
- "
/usagegives you no day-over-day history" is wrong. The plan usage breakdown has ad/wtoggle for the last 24 hours and the last 7 days, and it attributes recent usage to skills, subagents, plugins, and individual MCP servers. Those figures are approximate and computed from local session history on this machine, so other devices and claude.ai are excluded — but they exist. - "
/usagegives you no per-model split" is wrong for the session. The Session block prints aUsage by modelline with input, output, cache-read and cache-write counts per model. What it does not do is aggregate that across projects and across days. That gap is real, and it is the honest case for a tool like this.
There is also a first-party option the candidate never mentions: /insights analyzes your recent sessions on this machine and writes an HTML report to ~/.claude/usage-data/report.html. It is about how you work — friction points, misunderstood requests — rather than token arithmetic, and the analysis itself spends tokens against your plan. Different question, same local transcripts.
What is unverified
Nobody has run this. Be precise about which parts are load-bearing:
- Documented: the transcripts exist, are plaintext JSONL, live under
~/.claude/projects/, and hold every message and tool result. - Not documented: that per-request token counts are among the fields persisted in those files. The docs describe the transcript's contents as messages, tool calls, and tool results, and describe token counts as something
/usageand the status line surface — they never say the two meet on disk. If the counts are not in the JSONL, ccusage cannot be doing what it says it does, so this is the claim that matters. - Not documented at all: ccusage. Grepping the entire 77-page corpus for the string returns nothing. No official page names it, endorses it, or warns against it.
The check that would settle the mechanism half, before you install anything:
ls ~/.claude/projects/*/*.jsonl | head -1 | xargs grep -o '"output_tokens":[0-9]*' | head -5If that prints token counts, the substrate is real and the rest is a question of whether the tool parses it well. If it prints nothing, the tip's central claim is false and no amount of dashboard polish saves it.
If you adopt it
Treat the dollar figure as a proxy, not a bill. On a subscription you pay a flat fee; a locally computed API-list-price equivalent tells you how hard you are leaning on the plan, nothing about what you owe. Claude Code's own session figure carries the same caveat — the docs point at the Claude Console for authoritative billing, and note that the Session block's cost is aimed at API users rather than subscribers.
The habit worth copying, whichever tool you land on: a burn-rate readout visible while the agent runs beats a report you read afterwards. A second pane, or the rate_limits.five_hour percentage in your status line, both do that. A monthly summary does not.
Checkpoint
- Which of the four options gives you the server's own 5-hour number rather than one inferred from local files?
Show answerAnswer
The status line's
rate_limits.five_hour. It carriesused_percentageandresets_at(Unix epoch seconds), with the same pair forseven_day, and comes from the server's own rolling window — where/usage's Session block prices local token counts andccusageparses the local JSONL transcripts. Three constraints ride along: Claude.ai Pro and Max only, present only after the first API response in the session, and dropped once a window'sresets_atpasses, so any script reading it has to handle absence. If the 5-hour block was the whole reason you were reaching for a third-party tool, stop there and reach past it only for history and cross-project splits. - What single check would tell you whether ccusage's core premise — token counts in the transcripts — is true on your machine?
Show answerAnswer
Grep one transcript for a token field before you install anything:
ls ~/.claude/projects/*/*.jsonl | head -1 | xargs grep -o '"output_tokens":[0-9]*' | head -5. Token counts coming back mean the substrate is real and the rest is a question of how well the tool parses it; nothing coming back means the tip's central claim is false and no dashboard polish saves it. The result is yours to produce — nobody here has run it, and this is the load-bearing gap: the docs confirm the transcripts are plaintext JSONL under~/.claude/projects/holding every message, tool call and tool result, but never say per-request token counts are among the persisted fields. Weigh one thing before running ccusage itself, too —npx ccusage@latestpoints a third-party package at a directory the docs describe as unencrypted, so pin a version you have read. - Why is a locally computed dollar figure not your bill on a Pro or Max plan?
Show answerAnswer
Because it is an API-list-price equivalent computed locally from token counts, and on a subscription you pay a flat fee regardless of what those tokens would have cost. The figure proxies how hard you are leaning on the plan, not what you owe. Claude Code's own session figure carries the same caveat — the docs aim the Session block's cost at API users rather than subscribers, and point at the Claude Console for authoritative billing.