# ccusage — Real-Time Token Cost Tracker for Claude Code

> CLI that reads ~/.claude logs and breaks down Claude Code token spend by day, session, and project — pluggable into your statusline.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# ccusage — Real-Time Token Cost Tracker for Claude Code

## Quick Use
```bash
# Run instantly without install
bunx ccusage
# or
npx ccusage@latest
# Common views
ccusage daily          # per-day spend
ccusage session        # per-session breakdown
ccusage --json         # machine-readable output for statusline integrations
```

## 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


---
Source: https://tokrepo.com/en/workflows/ccusage-real-time-token-cost-tracker-claude-code-170532fa
Author: Skill Factory