ccusage
Analyze token usage and costs for coding-agent CLIs from local data, with daily, weekly, monthly and session reports.
- Source repo
- ccusage/ccusage
- Stars
- ★ 19k
- Last updated
- today
- License
- NOASSERTION
- Primary language
- Rust
- FA score
- 67/100 · Some gaps
At a glance
- Works with
- Universal · cross-platformCodex · Claude CodeChatGPT (Partial support)
- You'll need
- Typical use
- An individual developer who wants to see how much they spent this month on Claude Code versus Codex, broken down by day and month in tokens and USD.
- Main limitation
- Coverage is limited to what each CLI has written locally; it cannot reconcile full team or cloud-account spend.
- Source review
- 67/100 · Some gaps
What does this agent do, and when should you use it?
ccusage is a command-line tool that reads the local usage data written by coding-agent CLIs and turns it into daily, weekly, monthly and per-session reports. It covers sources including Claude Code, Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen, GitHub Copilot CLI, Gemini CLI, Antigravity, Grok Build CLI and ZCode, and ccusage daily, ccusage weekly, ccusage monthly and ccusage session merge every detected source into one report. Output defaults to colorful responsive tables, with --json for structured export, --no-cost to hide cost fields, --since/--until/--last date filtering, --timezone grouping and ccusage.json pricing overrides. It runs through npx or bunx without a global install, and is also packaged as a Nix flake. The tool does not call any model service; cost figures depend on bundled or cached pricing data. A Claude Code statusline hook mode and a 5-hour blocks report are also included, the former marked Beta.
ccusage parses the local session and usage records that each supported coding-agent CLI leaves on disk, groups raw token entries by day, week, month or session, and totals input, output, cache-write and cache-read tokens along with per-model cost. Subcommands include daily, weekly, monthly, session, plus blocks for Claude Code's 5-hour billing windows and statusline for a compact Claude Code status-bar hook (Beta). Source-scoped forms such as ccusage claude daily, ccusage codex daily or ccusage gemini daily restrict output to one source, while --all, --sections and --by-agent shape the unified report. Tables auto-collapse in narrow terminals and --compact forces compact layout; --json emits structured data, --breakdown adds per-model cost detail, --offline uses pre-cached pricing, ccusage.json overrides pricing per raw model name, and --instances/--project group or filter Claude Code usage by project.
- An individual developer who wants to see how much they spent this month on Claude Code versus Codex, broken down by day and month in tokens and USD.
- An engineer running several coding CLIs (Claude Code, Gemini CLI, Copilot CLI) who wants one combined usage report instead of checking each tool separately.
- A team that needs usage data inside its own scripts or dashboards, exporting via
--jsonand post-processing programmatically. - A Claude Code subscriber watching 5-hour billing windows with
ccusage blocksto avoid overrunning the active window. - A user who wants current usage always visible in the Claude Code status bar through the
statuslinehook (Beta). - A team splitting Claude Code spend by project or instance with
--instances --project.
How do you install or deploy this agent?
No installation is required; run it through a package runner, or build/run it via Nix.
# npm
npx ccusage@latest
# Bun
bunx ccusage
# pnpm / pnpx
pnpm dlx ccusage
pnpx ccusage
# Nix
nix run github:ccusage/ccusage -- daily
nix build github:ccusage/ccusageHow do you use this agent?
Running it with no arguments shows all detected sources reported by day. Common invocations:
# Core reports
bunx ccusage daily # all detected sources by day
bunx ccusage weekly # by week
bunx ccusage monthly # by month
bunx ccusage session # by session
bunx ccusage blocks # Claude Code 5-hour billing windows
bunx ccusage statusline # Claude Code status line (Beta)
# Single source
bunx ccusage claude daily
bunx ccusage codex daily --speed fast
bunx ccusage gemini daily
bunx ccusage pi daily --pi-path /path/to/sessions
# Unified reports and filters
bunx ccusage daily --all
bunx ccusage daily --sections daily,monthly,session --json
bunx ccusage daily --by-agent --json
bunx ccusage daily --since 2026-04-25 --until 2026-05-16
bunx ccusage daily --last 1
bunx ccusage daily --json --no-cost --timezone UTC
# Project dimension
bunx ccusage claude daily --instances --project myproject --jsonTo override prices, configure model names in ccusage.json.
What are this agent's strengths and limitations?
- One CLI aggregates 18+ coding-agent sources and can merge them into unified
daily/weekly/monthly/sessionreports. - Rich flag set for real workflows:
--json,--no-cost,--since/--until/--last,--timezone,--breakdown,--offline. - Runs through npx, bunx, pnpm dlx or Nix; bunx caches the package so repeat runs are fast.
ccusage.jsonoverrides pricing per raw model name, and--instances/--projectsplits Claude Code usage by project.- Reads data locally and performs aggregation itself, so no model API key is needed.
- Coverage is limited to what each CLI has written locally; it cannot reconcile full team or cloud-account spend.
- Costs hinge on pricing data, so figures can drift for new models unless you refresh the pricing snapshot or run
--offlinewith an updated one. - The
statuslineintegration is explicitly labeled Beta, so its behavior may change. - Repository metadata reports the license as NOASSERTION while the README states MIT; verify the LICENSE file before adopting.
- Needs a Node.js/Bun or Nix runtime, and network access on first run to fetch the package and pricing data.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| ccusage This agent | 67 · Some gaps | — | ★ 19k | today | Rust | Codex · Claude Code |
| ccxray | 73 · Some gaps | CLIFree + model costs | ★ 296 | today | JavaScript | Claude Code · Claude API |
| Tokscale – Track token usage across AI coding agents | 52 · Major gaps | CLIFree | ★ 5.7k | 1d ago | Rust | ChatGPT · Codex · Claude Code |
| Ordewell | 67 · Some gaps | CLIFree + model costs | ★ 203 | 1d ago | TypeScript | Codex · Claude Code · OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Read-only local usage analyzer with a small permission surface, so least_privilege scores 2; however README recommends running latest via npx/bunx with no version pinning or integrity check, and runtime may fetch LiteLLM pricing, with no user confirmation (user_confirmation 1). Data-flow transparency is good: docs enumerate source paths, env vars, and --offline semantics (2). Sensitive data: docs warn against secrets in config and offer --no-cost, but do not address whether local session data is sensitive (2). Dependency security rests only on a socket.dev badge and pnpm only-allow, no lockfile or audit evidence (1). External effects limited to read-only plus optional network (2). Rollback: only uninstall notes, no data/config rollback (1). Source attribution clear with MIT and author (2).
Docs are internally inconsistent on config priority: config-files.md and configuration.md describe env-var vs local-config precedence differently, so self_consistency is 2. Dependency availability documented with Node/Bun requirements and multiple package managers (2). Troubleshooting covers no-data, permissions, network, version conflicts, failure_messages 2.
Targets multi-agent CLI users with daily/weekly/monthly/session/blocks/statusline scenarios, audience_and_scenarios 3. Capability boundaries noted (read-only local data, estimated costs) but unsupported cases not systematically listed (2). Trigger precision: clear commands and namespaces, but default aggregation of all sources may surprise (2). Environment fit strong: multiple runtimes, Nix, offline, timezone, custom paths (3).
Information architecture excellent, well-sectioned docs (3). Install notes thorough across package managers with troubleshooting (3). Naming stability: many namespaces plus Beta statusline imply evolution risk (2). Examples and FAQ rich (3). Known limitations thin, only scattered Beta and estimated-cost mentions, no consolidated section (1). License: README and LICENSE are MIT but metadata says NOASSERTION, an inconsistency, so 2. Versioning: npm badge and monorepo version but no CHANGELOG (1). Maintenance responsibility: sponsor and author info present but publisher unverified (2).
Output usability strong: tables, JSON, compact mode, timezone and filters (3). Marginal value: real value for multi-agent usage/cost aggregation, but costs are estimates tied to a pricing snapshot (2). Cost-benefit: npx first run slow and pricing refresh needs network, mitigated by offline and caching (2).
Claim traceability weak: costs and usage are estimates with no reconciliation method against official billing (1). Cross-source corroboration limited to badges and external links (1). Fact/inference separation fair: docs distinguish display/calculate modes and estimation nature (2).
- README recommends running latest via npx/bunx with no version pinning or integrity check; assess supply-chain risk yourself.
- Costs are estimates from a LiteLLM pricing snapshot and may diverge from official billing; do not use as billing source.
- Default aggregates all detected sources, potentially reading more local data dirs than expected; scope with namespaces or paths.
- Config priority docs are inconsistent; rely on --debug output for actual behavior.
- License metadata NOASSERTION conflicts with MIT in README/LICENSE; verify before use.
FAQ
Does ccusage upload my usage data?
--offline uses pre-cached pricing instead of fetching it. Pricing data may be fetched over the network, but no upload of usage data to a service is described.Which coding CLIs are supported?
daily and friends without a source merges all detected sources.How accurate are the cost figures?
ccusage.json able to override prices per model. Missing or stale model prices will skew numbers, so pair --offline with an updated pricing snapshot.Can I wire it into automation?
--json for structured output, plus --sections and --by-agent to shape the report. Scheduling and downstream consumption are yours to build; the tool does not ship a daemon or server endpoint.