What Is ccusage? Claude Code Usage and Cost Reports, Setup, Dollar Amounts and Privacy

You type `npx ccusage@latest` (or `bunx ccusage`) in the terminal; ccusage reads the local log files of the coding agents on your computer (18 sources, including Claude Code, Codex, OpenCode, Gemini CLI and GitHub Copilot CLI) and gives you a table of token usage and estimated cost by day, week, month and session. No installation, account or key is needed; the analysis runs locally and it only reads the files. Important: the dollar amount is an estimate; the documentation says "costs are estimates and may not reflect actual billing." If you're on a subscription, the amount shows what the same usage would cost at pay-as-you-go prices, not what you pay. MIT-licensed.

What it does: Shows coding agents' token usage and estimated cost
Type: Command-line tool (npm package)
Where: Claude Code, Codex, OpenCode, Gemini CLI, Copilot CLI and more
Requirements: Node.js or Bun 1.3+
Dollar amount: An estimate; not your actual bill
Turkish: Not stated in the official documentation
Cost: Free (MIT); no account or key

What Is ccusage For?

It answers questions like "How many tokens did I spend on Claude Code this month?", "Which chat was the most expensive?" and "Which project's spending went up?" with a table in the terminal. Its source is the usage logs the agents keep on your own computer; you don't sign in to anything.

Getting a token and cost reportWhat you get: Daily, weekly, monthly tableNeeds a separate setup Finding the most expensive sessionWhat you get: Per-session breakdownNeeds a separate setup

Command	What it shows
`ccusage` or `ccusage daily`	All detected sources, by day.
`ccusage weekly` / `monthly`	By week and by month.
`ccusage session`	Per session (chat).
`ccusage blocks`	Claude Code 5-hour blocks (--active, --recent, --token-limit).
`ccusage statusline`	Single-line output for the Claude Code status line (Beta).
`ccusage claude daily`	Narrows the report to a single source (claude, codex, gemini, opencode…).

Who it's for: people who use Claude Code or Codex heavily and want to see their usage. It's also useful for estimating your usage limit (the window on a subscription).

How to Install and Run ccusage

No installation is needed; you run it directly with a package runner. The documentation recommends Bun for the quick start (Bun 1.3+). The minimum Node version isn't stated in the documentation or the npm registry. The commands are taken verbatim from the ccusage documentation.

With Bun› bunx ccusage

With Node› npx ccusage@latest

With pnpm› pnpm dlx ccusage

With npm› npm install -g ccusage

The Bun, yarn and pnpm equivalents are in the documentation too. You verify the installation with ccusage --version and ccusage daily.

In ~/.claude/settings.json› {"statusLine": {"type": "command", "command": "bun x ccusage statusline", "padding": 0}}

Without Bun, the command is npx -y ccusage statusline. The status line works offline by default.

ccusage blocks --live, which appears on the installation page, was removed in v18.0.0 according to the documentation itself; don't use it.

How to Use ccusage

You run the command in the terminal; there are options such as a date range, JSON output and a project filter.

May summary› npx ccusage@latest monthly --since 20260501 --until 20260531

With a model breakdown, as JSON› npx ccusage@latest daily --breakdown --json

Filter to one project› npx ccusage@latest daily --project my-project

Run without network access› npx ccusage@latest daily --offline

ccusage reads Claude Code logs from the ~/.config/claude/projects/ and ~/.claude/projects/ folders; if you keep them in another folder, set CLAUDE_CONFIG_DIR. By default Claude Code may only keep logs for 30 days (cleanupPeriodDays), so older months may come up empty.

Which Agents Does ccusage Work With?

Claude CodeYes	Local logs; the status line and 5-hour block features are only available here.
Codex, OpenCode, Amp, Droid, Gemini CLI, GitHub Copilot CLI and othersYes	Each one's local log folder is read; some sources are marked Beta or Experimental.
Multiple computersNo	It only reads local files on this machine; there's no multi-device support (issue #222 is open).

There's an open issue reporting that Codex's compressed (.jsonl.zst) logs are skipped (#1888, October 14, 2026).

What Does ccusage Access, and Does It Send Data?

Reads

The agents' local usage logs (for Claude Code, ~/.config/claude/projects and ~/.claude/projects; for Codex, ~/.codex and similar) and an optional configuration file.

Writes

The documentation says "read-only: ccusage only reads files and never modifies them." It writes the report to the terminal; the status line returns a single line of text to Claude Code.

Data

According to the documentation, the analysis is fully local and your usage data doesn't leave your computer. The network may be used for the price table (LiteLLM, models.dev and historical pricing sheets); --offline runs without the network. The documentation says nothing about telemetry; that doesn't mean "no telemetry," so check the open-source code for a definitive answer.

There are no records in GitHub Security Advisories or an OSV scan, and the repository has no SECURITY.md; this doesn't mean "safe."

Is ccusage Free? What Does the Dollar Amount Mean?

Yes. It's MIT-licensed open source; no plan, account or key. The README has sponsor promotions (such as a team cost-tracking product), but they aren't needed for the tool. The GitHub license field shows "NOASSERTION" because the LICENSE file is in a subfolder, not the repository root.

The dollar amount it shows is an estimate. The documentation: "Costs are estimates and may not reflect actual billing". If you're on a subscription (such as Pro or Max), the amount shows what the same usage would cost at pay-as-you-go API prices, not the fee charged for your subscription; the documentation describes this as "subscription value" and doesn't name the plans. The cost of a model without a price may silently come out as 0 (issue #1736).

Allowed

MIT: free to use and modify

Not allowed

Don't use the dollar amount as an invoice or budget evidence

Common Problems and Fixes

What's happening	What to do
"No Claude Code usage data found"	The logs should be under ~/.config/claude/projects or ~/.claude/projects; if they're somewhere else, set CLAUDE_CONFIG_DIR (several folders separated by commas).
Older months are empty or incomplete	By default Claude Code may only keep logs for 30 days; the cleanupPeriodDays setting can be changed. Deleted logs don't show up.
A model's cost shows as $0	If the model isn't in the price database, or there's no price data in offline mode, the cost comes out as 0. Update, or run without --offline. Reported by users Issue #1736 is open.
Reported by users Part of my Codex usage is missing	Issue #1888 (October 14, 2026, open): compressed logs are skipped.
The total doesn't match what Claude Code itself shows	The cost is an estimate; --mode (auto, calculate, display) gives different results. Reported by users Issue #1638.

How to Uninstall ccusage

If you ran it without installing: There's no permanent installation; only the package manager's cache remains.
Remove the global install: npm uninstall -g ccusage (the Bun, yarn and pnpm equivalents are in the documentation).
Turn off the status line: Delete the statusLine block in ~/.claude/settings.json.

Frequently asked questions

What is ccusage for?

It builds a table of token usage and estimated cost by day, week, month and session from the local logs of the coding agents on your computer (Claude Code, Codex, Gemini CLI, etc.).

Where does it read Claude Code logs from?

From the ~/.config/claude/projects and ~/.claude/projects folders; if both exist, it merges them. If CLAUDE_CONFIG_DIR is set, that's used instead of the defaults.

Do I pay the dollar amount it shows?

No, it's an estimate. The documentation says the costs may not reflect actual billing. If you're on a subscription, the amount shows what the same usage would cost at pay-as-you-go prices; it's not your bill.

How does it calculate cost, and does it use the internet?

It multiplies the token count by model prices (LiteLLM, models.dev and historical pricing sheets). In the default mode, if a log already contains a cost, it uses that. In a default run, price data may be refreshed from the network; --offline uses cached or bundled prices without going online (two documents describe this slightly differently).

Is my data sent anywhere?

According to the documentation, the analysis is fully local, your usage data doesn't leave your computer, and the tool only reads files. There may be network requests for the price table. The documentation says nothing about telemetry.

Do I need Node.js or Bun?

You need a package runner to run it: Node.js for npx, Bun 1.3+ for bunx. The documentation recommends bunx for the quick start.

Related guides

Sources

Not clear in the official sources: Whether there's telemetry (no statement in the documentation) · the exact address price data is fetched from · the minimum Node.js version (no engines field) · the exact equivalent of the Claude Code log path on Windows · an official interpretation for subscription users (the documentation doesn't name Pro or Max). Each is covered in its section.