What it is
ccusage reads the usage logs that Claude Code and other agent CLIs keep on your machine and reports tokens and estimated cost by day, week, month or session. For Claude Code it also shows the 5-hour billing blocks with a live view and offers a compact statusline (in beta) for Claude Code's status bar.
It runs with `npx ccusage@latest` (or bunx, pnpm dlx, Nix) and needs no account or API key. The README lists 18 sources, including Claude Code, Codex, OpenCode, Amp, Goose, Kilo, Gemini CLI and GitHub Copilot CLI. Prices come from LiteLLM, models.dev and built-in historical schedules, cached locally, with an `--offline` mode.
Our review
ccusage has become the default local meter for coding-agent usage. It has about 19,100 GitHub stars, npm counted roughly 871,000 downloads in the 30 days to 18 October 2026, and it ships almost daily: v20.0.34 on 15 October to v20.0.41 on 22 October. Started by ryoppippi, it now sits under a ccusage organisation, and the codebase is Rust, still distributed through npm.
The cost column needs reading carefully. In the default auto mode it uses the costUSD that Claude Code stores where present and otherwise multiplies tokens by published per-token prices. The docs say plainly that costs "may not reflect actual billing" and that tool calls such as web search are not included. On a Pro or Max subscription the figure is not your bill; it is what the same work would have cost at pay-as-you-go rates.
The less obvious limit is history. Claude Code keeps local transcripts for 30 days by default (the cleanupPeriodDays setting), and ccusage can only count what is still on disk. Anyone who wants a quarter's trend has to raise that setting first, or export `--json` snapshots on a schedule.
Usage data never leaves the machine, according to the docs, but by default ccusage does refresh its pricing cache over the network; `--offline` stops that. Reports separate input, output, cache-creation and cache-read tokens per model, which is the breakdown you need to tell whether a prompt-caching change or a token-saving plugin actually helped.
Its scope is one machine. There is no documented server or team view, so a manager comparing ten developers is collecting and summing ten JSON files by hand, and each of them is only as complete as that laptop's log retention.
Where it earns its place
A developer trialling a token-saving plugin such as RTK
Prove whether it actually reduces usage
Run `ccusage daily --json` for a week before and a week after installing it and compare input and cache-read tokens per model. Takes minutes and costs nothing; the comparison is only as fair as the two weeks' workloads.
An engineering manager paying for Claude Max seats
Decide whether moving the team to API billing would be cheaper
Each developer runs `ccusage monthly --json` and shares the file; the totals show what the same usage would cost at API rates. Because there is no shared view, collecting and summing the files is manual.
A freelance developer billing several clients
Attribute agent spend to each client project
`ccusage claude daily --instances --project <name>` groups Claude Code usage by project; the API-equivalent figure is a defensible line item if the contract bills tooling at cost.
Before you commit
- Setup
- `npx ccusage@latest` prints a daily report in seconds; bunx caches the package so repeat runs are faster. Add `ccusage statusline` to Claude Code's status line hook for a live figure.
- Integrations
- Reads local logs from 18 agent CLIs, including Claude Code (~/.claude and ~/.config/claude/projects), Codex, OpenCode, Gemini CLI and Copilot CLI; outputs tables or JSON; pricing overrides go in ccusage.json.
- Data and privacy
- Analysis is local and usage data is not uploaded, per the docs; pricing data is fetched and cached unless you pass --offline. MIT licence, so commercial use is unrestricted.
- Cost at scale
- Free, with no paid edition; it is sponsor-funded. The only cost is the habit of running it on every machine you want counted.
- Limits
- Dollar figures are estimates that exclude web search; Claude Code deletes transcripts after 30 days unless cleanupPeriodDays is raised; no team aggregation. Only 4 open issues at last check.
What's good
- Fully local reports with no account
- 18 agent CLIs in one report
- Splits cache-creation and cache-read tokens per model
- 5-hour block view, statusline and --json output
What's not
- Costs are API-equivalent estimates and exclude web search
- History limited to what the agent keeps on disk (30 days for Claude Code by default)
- No team or server mode
Best for
Anyone who wants to track or compare token use across agent sessions.
Alternatives
ccusage: common questions
- Is ccusage worth it?
- ccusage is the meter every heavy agent user should run, provided they read its dollar column as what the work would have cost on the API, not what they paid. We rate it 4.4 out of 5.
- How much does ccusage cost?
- Free and open source (MIT).
- What are the downsides of ccusage?
- Costs are API-equivalent estimates and exclude web search; history limited to what the agent keeps on disk (30 days for Claude Code by default); no team or server mode.
- Who is ccusage best for?
- Anyone who wants to track or compare token use across agent sessions.
- How much does ccusage cost for a team or in production?
- Free, with no paid edition; it is sponsor-funded. The only cost is the habit of running it on every machine you want counted.
- Is ccusage safe for company data?
- Analysis is local and usage data is not uploaded, per the docs; pricing data is fetched and cached unless you pass --offline. MIT licence, so commercial use is unrestricted.
- What are the best ccusage alternatives?
- The closest alternatives we have reviewed are rtk (Rust Token Killer) and Claude Code Router.
Answers checked Oct 23, 2026.
Make ccusage? Show this rating on your site
