ccusage: the reference tool for Claude Code token costs

Running it

# daily totals across every detected source, the default
npx ccusage@latest

# other package runners
bunx ccusage
pnpm dlx ccusage
nix run github:ccusage/ccusage -- daily

# other groupings
npx ccusage@latest weekly
npx ccusage@latest monthly
npx ccusage@latest session
npx ccusage@latest blocks

It is not a Claude Code tool any more

This is the change most people have missed. A bare ccusage daily now aggregates every agent CLI it detects on the machine, and each source has a focused command that scopes the report to one.

The commands

The flags worth knowing

# this month, split by model
npx ccusage@latest monthly --last 1 --breakdown

# Claude Code only, grouped by project
npx ccusage@latest claude daily --instances

# machine-readable, for a dashboard or a cron job
npx ccusage@latest daily --json --since 20260701

The per-command flags worth remembering are --instances and --project on the daily report, --start-of-week on the weekly report, and --id on the session report when you already know which session you are chasing.

Blocks, and the live mode that is gone

A block is one 5-hour billing window. It starts with your first message and lasts exactly five hours, which is the same boundary your plan uses, so the block report is the closest ccusage gets to a quota view.

# only the block you are in, with time remaining and projected totals
npx ccusage@latest blocks --active

# the last three days of blocks
npx ccusage@latest blocks --recent

# treat your largest previous block as the ceiling
npx ccusage@latest blocks --token-limit max

The statusline command

This is the replacement for live mode and it is better, because it costs no screen space. Claude Code runs a command to render its status line, and ccusage ships one.

{
  "statusLine": {
    "type": "command",
    "command": "bunx ccusage statusline",
    "padding": 0
  }
}

You get one line in your prompt with the active model and effort level, session cost, today's total, the current block cost with time remaining, burn rate per hour, and context usage as a percentage. It runs offline against cached pricing by default, which is what keeps it fast enough to render on every message.

Why its numbers are the right ones

The hard part of this problem is not reading JSONL. It is not double counting.

1. Resumes replay history. Resuming a session can write earlier messages again, so the same logical request appears in more than one place.
2. Retries duplicate. A retried request can be recorded twice.
3. Subagents write their own transcripts. Sidechain work lands in a separate file under the parent session directory.

ccusage builds a deduplication key from the message ID and the request ID, so each logical request counts once regardless of how many times it appears on disk. When two records collide it prefers the non-sidechain entry and the one with the larger token total, which is the version that reflects the completed request. A tool that naively sums every usage object it finds will report a larger number, and that number will be wrong.

Where it stops

Questions people ask

Keep reading