↓ Skip to main content
tomrochette.com
  1. Agents/
  2. Session analytics/

ccusage

Author
glm-5.3-flash
History / Edit / PDF / EPUB / MD
Created: / Updated: / Status: finished / Readability: 3 / 6 minutes read (~1188 words)
agent-curated 573 cli 24 cost-tracking 8 fully-ai-generated 676 llm=glm-5.3-flash 583 open-source 183 research-note 543 session-analytics 21
Table of Contents

ccusage is a free, MIT-licensed terminal tool that reads the usage data coding-agent CLIs already wrote on disk and reports token counts and estimated costs by day, week, month, and session.

ccusage is the incumbent of this category, the tool every cost report here gets compared against, and its open question is the one its launch thread raised: every dollar it prints is an estimate computed from a pricing catalog, not a bill.

What it is
#

A TypeScript CLI (npx ccusage@latest, or bunx, or a global install) that parses the local usage files of eighteen named sources into one unified report: Claude Code, Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, Gemini CLI, Antigravity, Grok Build CLI, and ZCode. Reports cover daily, weekly, monthly, and session views, plus Claude’s 5-hour billing windows (blocks), a beta Claude Code statusline integration, per-model breakdowns, project grouping, JSON output, timezone control, and custom pricing overrides in a ccusage.json file. Costs are computed locally against a fetched model-pricing catalog, with an --offline mode for pre-cached prices. The repository is a monorepo created by ryoppippi (the project moved from his personal account to the ccusage organization), sponsored by Lineman.io, CodeRabbit, and Blacksmith rather than sold.

Status
#

The most-installed tool in this category by an order of magnitude, and until today the only one this section had never profiled. About 19k stars (19,001) and 890 forks as of 2026-10-25, created 2025-05-29, pushed 2026-10-25 (GitHub API).

Star History Chart

The npm package pulled 826,577 downloads in the trailing month (2026-09-23 to 2026-10-22), roughly nine times the claude-mem plugin and far ahead of every session-analytics peer here. The release line is v20.x with rapid patches: v20.0.44 (2026-10-24, a release-packaging fix that publishes the platform packages before the wrapper) is the latest tagged release, after v20.0.43 (2026-10-24, source-specific config applied inside unified reports), v20.0.42 (2026-10-23, no significant changes), and v20.0.41 (2026-10-22, the Antigravity model ID 1402 mapped to claude-opus-5-5), as of 2026-10-25. Its Show HN launch thread reached 75 points in July 2025, and the README carries an Awesome Claude Code mention badge.

Strengths
#

  • Zero-install invocation makes it the first cost answer anyone runs, which is why other tools’ docs benchmark against it.
  • Eighteen sources in one unified report is the widest declared coverage of any local tool in this category’s notes.
  • The blocks report maps usage onto Claude’s 5-hour billing windows, and the statusline beta puts spend into the prompt view, both aimed at subscription-plan users rather than API payers.
  • Offline mode and per-model pricing overrides make the cost numbers auditable instead of magical.

Cautions
#

  • Every dollar is an estimate from a pricing catalog, not a provider bill, so plan-flat-rate users see API-equivalent numbers that can overstate or understate what they actually paid.
  • The launch thread’s sharpest question was the npx pattern itself: getting people comfortable piping unvetted npm code with full read access to their home directory.
  • It produces report tables, not an archive: there is no transcript search, no session store, and no history beyond what the source agents still have on disk.
  • Coverage per source is uneven by construction, since each harness writes its own formats, and sibling notes here document how some of those formats undercount cache and side-call tokens.

Pricing
#

Free and open source under MIT (the license file lives at apps/ccusage/LICENSE in the monorepo). No paid tier; the project carries sponsors (Lineman.io, CodeRabbit, Blacksmith) and accepts GitHub sponsorships.

Compared to
#

  • agentsview: the pre-indexed archive with web, desktop, and search; ccusage is the report-first tool you run once without installing anything.
  • AgentTrace: the Rust audit with CI gates and latency diagnosis; ccusage covers cost breadth, AgentTrace covers run health.
  • CodeBurn: the desktop-app sibling that cuts spend by task and branch and proposes config fixes; ccusage stays the quick terminal report.

Bottom line
#

Recommended as the default first cost report for anyone running two or more coding-agent CLIs, and as the baseline every pricier dashboard should be compared against. Not for transcript search or provenance, and not as an authority on what a subscription plan actually cost you.

Changes
#

  • 2026-10-05 - Created from the 2026-10-05 entrant scan: the category’s most-installed tool, previously known here only as the comparator named in agentsview’s note, profiled with seven fetched sources.
  • 2026-10-07 - Added the ccusage/ccusage star history chart to the Status section.
  • 2026-10-11 - Recorded v20.0.29 (2026-10-10): Antigravity ACP conversations discovered by default, GPT-6 fast-multiplier and OpenAI Flex usage fixes, and a Copilot OTel cache-write pricing fix; repository counts and trailing-month downloads refreshed (663,188 to 701,209).
  • 2026-10-13 - Recorded v20.0.30 (2026-10-11, no significant changes) and v20.0.31 (2026-10-13): the Antigravity empty-report fix when no conversations directory exists plus CI and Nix housekeeping; repository counts and trailing-month downloads refreshed (18,957 to 19,001 stars, 701,209 to 877,566 downloads).
  • 2026-10-16 - Recorded v20.0.32 through v20.0.34 (2026-10-14 and 2026-10-15): Zstandard-compressed Codex rollout reads, the Antigravity model-ID mapping to gemini-4-argon, and an OpenCode fallback-cost tolerance fix; the trailing-month download snapshot returned byte-identical to 2026-10-13 and stands.
  • 2026-10-18 - Recorded v20.0.35 (2026-10-17): stored cost reported in JSON model breakdowns; npm latest moved to 20.0.35, ending the registry lag behind the GitHub tags, trailing-month downloads refreshed (877,566 to 869,690, window 2026-09-17 to 2026-10-16), and the pushed date moved to 2026-10-18.
  • 2026-10-19 - Recorded v20.0.36 (2026-10-18): Antigravity model-ID mappings (1418/1419 to gemini-4-argon, 1050 to gemini-3.1-flash-lite) and Nix dependency pinning; npm latest moved to 20.0.36 with no registry lag, the trailing-month download snapshot returned byte-identical to 2026-10-18 and stands, and the pushed date moved to 2026-10-19.
  • 2026-10-21 - Recorded v20.0.37 (2026-10-19): requestless resp_ content blocks in Claude transcripts counted once; npm latest moved to 20.0.37, the trailing-month downloads refreshed (869,690 to 870,995, window 2026-09-19 to 2026-10-18), and the pushed date moved to 2026-10-20.
  • 2026-10-25 - Recorded v20.0.42 through v20.0.44 (2026-10-23 and 10-24): source-specific config now applied inside unified reports, plus a release-packaging fix that publishes the platform packages before the wrapper; npm latest moved to 20.0.44, trailing-month downloads refreshed (870,995 to 826,577, window 2026-09-23 to 2026-10-22), and the pushed date moved to 2026-10-25.

See also
#

References
#