ccusage: Track Claude Code Token Usage and Cost
ccusage reads local logs to report Claude Code token usage and estimated cost by day, week, month or session. Commands, use cases, pros and cons.
By Claudekit Team Published 1 min read
- Type
- CLI
- Pricing
- Open Source
- Repository
- github.com
- GitHub stars
- 19,153
- Website
- ccusage.com
ccusage is an open-source CLI that analyzes token usage and estimated costs from the local data coding agents write to disk. It started as a Claude Code tool and now covers many agent CLIs. The repo moved from its creator’s account to the ccusage organization.
Run it
No install required:
npx ccusage@latestReports by period, across every detected source:
ccusage daily
ccusage weekly
ccusage monthly
ccusage sessionClaude Code only:
ccusage claude dailyOther sources follow the same pattern, for example ccusage codex daily or ccusage gemini daily. See the README for package-runner and global install options.
Use cases
- Plan sizing: see whether your real usage justifies a bigger or smaller Claude plan.
- Finding expensive habits: compare sessions to spot runaway context, oversized skills or chatty MCP servers.
- Team reporting: export reports to compare usage between projects.
- Before and after: measure whether trimming
CLAUDE.mdor disabling plugins actually reduced tokens. Our getting started guide covers context habits worth measuring.
Pros
- Zero setup with npx; reads data already on your machine.
- Clear daily, weekly, monthly and session views.
- Multi-agent support if you use more than one coding CLI.
Cons
- Costs are estimates, not billing data.
- Depends on local log formats that can change between agent releases, so keep it updated with
@latest. - Shows what happened, not why; pair it with Claude Code’s own
/usageview and/doctorchecks.
Related: Claude Code, and if you are evaluating plugin overhead, the plugins guide.
Frequently asked questions
Does ccusage send my data anywhere?
It analyzes usage data stored locally by your coding agent CLIs and prints reports in your terminal. Review the repository if you need certainty for your environment.
Are the cost numbers what I actually pay?
No. They are estimates from token counts. On a flat-rate Claude plan you are not billed per token; use the figures to compare usage, not as an invoice.
Does it only work with Claude Code?
No. It supports many agent CLIs, including Codex, OpenCode, Gemini CLI and GitHub Copilot CLI. Use ccusage claude daily to limit a report to Claude Code.