ccusage — Real-Time Token Cost Tracker for Claude Code

Introduction

ccusage is a zero-config CLI that reads Claude Code local logs from ~/.claude/ and produces accurate token-usage and cost reports. It groups spend by day, session, project, or model so you can see — at a glance — where your subscription or API budget actually went, and pipe live numbers into your terminal statusline.

What ccusage Does

• Parses every conversation log in ~/.claude/ and extracts per-message token counts.
• Aggregates spend across days, sessions, and projects with one command per view.
• Emits JSON or text — JSON is designed to be eaten by Starship, tmux statuslines, or shell prompts.
• Computes both input/output tokens and dollar cost, using the model price each message used.
• Runs entirely offline — no API call, no network round-trip; it is reading your own files.

Architecture Overview

ccusage is a TypeScript package executed via Bun or Node. On invocation it walks ~/.claude/projects/, parses each session JSONL log, joins messages with model pricing, and emits a structured report. Because it never talks to Anthropic servers, it works in restricted networks and adds zero latency to your shell prompt when used as a statusline source.

Self-Hosting & Configuration

• Zero install: bunx ccusage or npx ccusage@latest runs the latest version on demand.
• Optional global install: bun add -g ccusage.
• Output formatters via flags: --json, --csv, --breakdown, --since, --until.
• Statusline integration: pipe ccusage --json today to a JSON reader (jq) and embed in your shell prompt.
• Pricing tables ship with the binary; update by re-running with the latest version.

Key Features

• Reads the canonical local log; numbers match the official billing dashboard.
• Multiple grouping axes — by day, session, project, or model — in one command.
• Statusline-friendly JSON output is its headline use case.
• Pure-local execution — works in offline or air-gapped setups.
• Updated pricing for every active Claude model (Opus, Sonnet, Haiku, 1M-context tiers).

Comparison with Similar Tools

• Anthropic web dashboard — definitive source, but no per-project breakdown and no live statusline feed.
• OpenAI usage scripts — different ecosystem; ccusage is Claude-only and smarter about its log format.
• tokens MCP servers — server-side counters; ccusage works on the CLI logs you already have.
• Custom shell scripts on ~/.claude/ — what people built before ccusage; ccusage replaces that with a maintained tool.
• Claude Code built-in /cost — same data per session; ccusage adds cross-session aggregation and history.

FAQ

Q: Does ccusage need network access? A: No — it reads local files only.

Q: Will it work with team or enterprise subscriptions? A: Yes, as long as the local agent writes logs under ~/.claude/, which it does by default.

Q: How fresh are the numbers? A: As fresh as the log file. Claude Code flushes after each turn, so ccusage is effectively real-time.

Q: Can I add it to my Starship prompt? A: Yes — pipe ccusage --json today into a Starship custom module or any shell prompt that consumes JSON.

Sources

• https://github.com/ryoppippi/ccusage
• https://www.npmjs.com/package/ccusage