Repo review · Tested August 23, 2026
ccusage keeps the books for your coding agents
ccusage is a local Claude Code usage tracker and multi-agent reporting CLI for tokens, estimated API costs, and terminal status. Use Anthropic's own tools for plan limits and billing.
Claude Code, Codex, and the growing circle of AI coding agents that live in a terminal all leave usage records behind. Every session appends models, token counts, and timestamps to a file on your own disk. None of them leaves you one bill.
ccusage reads those local files and turns them into daily, monthly, session, project, and rolling five-hour reports. It is a Claude Code usage tracker first, and its newer commands also cover Codex, OpenCode, Amp, Goose, Gemini CLI, and GitHub Copilot CLI. The totals are local and scriptable. They are not Anthropic’s authoritative account balance.
One translation before the rest of this review makes sense. ccusage prices your local token counts at published API rates, which is why everything below calls its dollar figures API-equivalent cost. If you pay per API call, that number is close to a bill. If you are on a Pro or Max subscription, it is a shadow price: what those tokens would have cost bought individually, bearing no fixed relationship to the flat fee you actually pay.
That boundary is the whole decision. ccusage is good at keeping the books it can see. It cannot certify the books it cannot.
Tested: commit
bd7f89b469aee5635fb2e6722dd6d70f2d113ac1on August 23, 2026. Setup: two npm packages, installed in 504 ms. Scope: exact controlled ledgers, default reports through a generated 600 MiB history, and pinned ccusage inside official Claude Code 2.1.241. Result: the ledgers matched, the real statusline rendered, ordinary overlapping refreshes cleaned up, and exiting during a large refresh left a transient process tree and Node crash. Verdict: try it for local usage reporting and a Claude Code statusline.
One ledger, several coding agents
ccusage began as a terminal report for Claude Code’s local JSONL history. At the tested revision, version 20.0.20, its main command grouped usage by day, month, session, project, or rolling five-hour block.
There is nothing to sign up for and no history to import. npm install ccusage@20.0.20 pulled two packages in 504 milliseconds, and npx -y ccusage@20.0.20 runs the same code without installing anything at all. What arrives is a small Node launcher plus one compiled binary for your platform, a split that matters a great deal by the end of this review. Point it at a machine that has been running coding agents and it finds the histories itself. Here is the monthly view of the history we tested against, with offline pricing:
| Month | Agent | Models | Input | Output | Cache create | Cache read | Total tokens | Cost |
|---|---|---|---|---|---|---|---|---|
| 2026-07 | Claude | Haiku 4.5, Opus 4.1, Sonnet 4 | 309,204 | 65,849 | 34,353 | 100,193 | 509,599 | $2.86 |
| 2026-08 | Claude | Haiku 4.5, Opus 4.1, Sonnet 4 | 981,072 | 208,137 | 109,563 | 318,392 | 1,617,164 | $9.36 |
| 2026-08 | Codex | GPT-5.3 Codex | 600 | 100 | 0 | 400 | 1,100 | $0.00 |
| Total | 1,290,876 | 274,086 | 143,916 | 418,985 | 2,127,863 | $12.22 |
Two vendors in one table is the aggregation argument in a single screen: 2,127,863 tokens and $12.22 of API-equivalent cost, split by agent and by model, scrolling right to a cost column no provider would have filled in for us. Claude and Codex share no account, no pricing page, and no file format, and neither company has any reason to add them up.
The five-hour block needs its own paragraph, because it is the one unit here that does not explain itself. It is the window ccusage uses to answer “how much have I spent in the stretch I am currently in,” and blocks --active is the long form of the same idea:
$ ccusage blocks --active
Block Started: 2026-08-23 14:00:00
Time Elapsed: 0h 42m
Time Remaining: 4h 17m
Current Usage:
Input Tokens: 8,445
Output Tokens: 1,005
Total Cost: $0.35
Burn Rate:
Tokens/minute: 1,406
Cost/hour: $2.09
Projected Usage (if current rate continues):
Total Tokens: 375,358
Total Cost: $9.31Every number in that block, including the boundary times and the projection, is ccusage’s own arithmetic over local files. None of it was read from Anthropic.
Cost carries a second asterisk. Claude Code writes its own cost figure into the history it stores, and ccusage can independently calculate one from token counts and a bundled or online pricing catalog. The --cost-source both mode prints the two side by side, which is how you find out when they disagree. That split is genuinely useful for comparison and trend reporting. It is still not an invoice, however confidently the terminal renders the dollar sign.
The adoption numbers are substantial for a repository created in May 2025. On August 23, 2026, GitHub reported 18,129 stars and 809 forks, while npm reported 411,545 downloads over the preceding 30 days. Maintenance is much more concentrated than the star count: GitHub attributed 1,118 commits to the lead account and 17 to the next contributor. Popularity says people have found the counter. Concentration says one person still keeps much of the machinery moving.
A live usage line inside Claude Code
Claude Code can run a local command on a persistent line beneath the conversation. That statusline turns ccusage from a report you have to remember into one that stays in view. Against our controlled history, it read:
🤖 Sonnet 4 (high) | 💰 ($0.42 cc / $0.18 ccusage) session / $0.27 today / $0.27 block (4h 17m left) | 🔥 $1.80/hr 🟢 (Normal) | 🧠 25,000 (13%)The $0.42 cc came from Claude Code; the $0.18 ccusage was calculated from the same local records. ccusage matched every expected field in our controlled ledger, and a known $0.08 event changed only the locally calculated totals. We then pinned the same command inside official Claude Code 2.1.241, sent one fixed-response prompt, and saw the model, cost, block, burn rate, mode, and context fields render beneath the reply.
Fast reports, expensive refreshes
Small histories are the easy case, so we padded a generated offline history while keeping the meaningful records fixed. Default daily reports stayed quick:
| Generated history | Elapsed time | Peak resident memory |
|---|---|---|
| 10 MiB | 0.08 s | 62.6 MiB |
| 250 MiB | 0.55 s | 296.5 MiB |
| 600 MiB | 1.19 s | 602.7 MiB |
The live statusline was much heavier. Against the generated 600 MiB history, one refresh took roughly seven seconds and the process tree reached just under 1 GiB in aggregate. Two overlapping refreshes cleaned up correctly when Claude Code replaced them.
Exiting during a final refresh was rougher. The compiled worker remained for about 8.7 seconds, the shell and Node launcher survived for at least 11.2 seconds, and Node aborted with SIGABRT. The final process list was empty, so this was delayed, noisy cleanup rather than a lasting runaway.
Where local estimates are enough
ccusage fits when you want terminal-native reports across projects or coding agents, prefer local files over a hosted dashboard, and can treat dollar values as API-equivalent estimates. Its JSON output and grouping commands make it useful for personal retrospectives, lightweight team scripts, and questions like which project or model consumed yesterday’s tokens.
The Claude Code statusline is also a good fit for a normal local history when a person is present to notice odd behavior. Pin the version, keep the display modest, and check the process list if a very large history makes exits feel sticky.
Use Claude Code’s /usage command and Anthropic’s account surfaces when the question is how much of a first-party plan remains. Reddit threads about ccusage differing from Claude Console and about finding an accurate Max-plan tracker are reminders that “usage” can mean local tokens, API-equivalent cost, or subscription allowance. Those are different ledgers.
A focused editor extension or dashboard may be better if you want persistent charts. Direct parsing may be better if an internal system owns one narrow schema. Provider billing APIs or consoles are better when money must reconcile. ccusage wins when the terminal is the interface and breadth across local agent histories matters more than provider authority.
Keep the ledger, verify the statement
Try ccusage for local coding-agent reports and a Claude Code statusline. Its controlled totals matched, its pinned command rendered inside the actual Claude Code CLI, and its default reports stayed responsive through our generated 600 MiB history.
The limits are equally concrete. API-equivalent costs are not a subscription balance. A large live refresh consumed substantial memory, and exiting mid-refresh left a transient process tree before a Node crash and eventual cleanup. Multi-agent accumulation, provider reconciliation, cross-platform behavior, and naturally grown multi-gigabyte histories remain unproven. One maintainer writing almost all of the commits is what makes the tool this current and this coherent, and it is also the reason a pinned version is the sensible way to depend on it.
ccusage is a capable bookkeeper. Keep Anthropic’s statement next to its ledger, and glance at the process list before you close the books.