ccusage

What it is

ccusage is a free command-line tool that tells you how many tokens your coding agents have used and roughly what that would cost. Tokens are the chunks of text AI models read and write, and they're how AI usage is measured and billed.

Your agents already keep a log of every conversation on your computer. ccusage reads those logs and turns them into tables by day, week, month or session. It started with Claude Code (the name means "Claude Code usage") and now covers Codex, Gemini CLI, Copilot CLI, OpenCode, Amp, Antigravity and about a dozen more.

It's MIT-licensed and made by ryoppippi. It's been around since May 2025, is now written mostly in Rust, and ships new versions almost every day.

What actually happens when you use it

1. You run one command. npx ccusage@latest downloads the latest version and runs it once. There's nothing to install or configure.
2. It finds your logs. It looks in the default folders each agent uses and picks up whatever it finds.
3. You get a table. Each row shows input and output tokens, cached tokens, the models used and an estimated cost in US dollars.
4. You can dig in. ccusage monthly, ccusage session or ccusage claude daily --instances break things down by month, by conversation or by project. ccusage blocks shows Claude's 5-hour usage windows.
5. It can live in your status bar. There's a beta status line for Claude Code that shows your usage as you work.

It only reads. It doesn't change your agent's settings or send your logs anywhere.

What people like

• It's effortless. One commenter on the Hacker News launch thread said they like how easy it is to run with npx or bunx, with nothing to install.
• It shows what your subscription is really worth. This is the main reason people run it. It shows what you would have paid at API rates, and people use that to judge their plan. One Max user reported about $5k of tokens on a $100 plan.
• It works across agents. People use it to compare tools, for example checking Codex usage against a $20 plan and against paying per token elsewhere.
• It's a common yardstick. When people build tools that claim to save tokens, they often use ccusage to measure the difference.
• Counting bugs get fixed quickly. When a user found Codex usage counted 10 to 20 times too high, they sent a fix, and it was merged about two weeks later. A recent double-counting bug in some Claude setups was diagnosed in detail and closed the next day.

What people run into

• The dollar figure isn't your bill. It's what the same tokens would cost at the public API price. The docs say plainly: "Costs are estimates and may not reflect actual billing." If you're on a subscription, you paid your plan price, not this number.
• Counts can be wrong for a while. Agents change their log formats often, and ccusage has to catch up. Recent examples include Claude usage counted two to three times behind certain proxies, and the Codex over-counting. One API user found ccusage didn't match their Anthropic console, and a commenter thought the counting method was flawed at the time.
• Updates can change what it sees. One user found it stopped showing Claude usage after July, and the reply was to update to the latest version.
• Your history quietly shrinks. Claude Code deletes conversation logs after 30 days by default, so older months shrink every time you run it. One user only found out after noticing a drop in ccusage.
• It only sees one computer. If you use agents on a laptop and a desktop, each one shows only its own usage. A request to combine several computers has been open since 2025, and people still ask about it on Reddit.

Before you install

• You're running code from the internet. npx downloads and runs the newest version, which can access your whole machine. A Hacker News commenter raised exactly this concern. It's a popular, well-watched package, but if that worries you, install a fixed version instead of using @latest.
• Your logs stay on your computer. The docs say all analysis happens locally. It can look up current model prices online; --offline uses the built-in price list instead.
• Keep your history longer if you care about trends. Raise cleanupPeriodDays in your Claude Code settings so old logs aren't deleted after 30 days.
• Hide costs before sharing screenshots. --no-cost removes the dollar columns.
• The "1 open issue" count is misleading. Issues from new contributors are closed automatically and reopened only if a maintainer thinks they're worth it. The project is well looked after, but that number doesn't mean there are no bugs.

The short version

ccusage is the easiest way to see how much you actually use your coding agents, and it costs nothing to try. Treat the dollar figure as "what this would cost at API prices", not as money you spent. Expect the odd counting bug when an agent changes how it writes logs, and update when numbers look off. For a quick, private look at where your tokens go, it's still the tool most people reach for.