Summary
Token usage at a glance
npx promptreports-cliThe default command. Scans your Claude Code sessions for token consumption, cost breakdown, and cache hit rates.
Summary is the first command every vibe coder runs. It scans ~/.claude/projects/ for every .jsonl session file, parses each session, and produces a comprehensive report: total tokens, cost by model, cache hit rate, top consumers, token breakdown (where are tokens going — input, output, cache writes, cache reads), and actionable optimization suggestions. Runs fully offline on your machine. Zero data leaves your computer unless you follow up with `push`.
On this page
Prerequisites
- At least one Claude Code session in ~/.claude/projects/
- Node.js >= 18
Flags & Options
| Flag | Description | Default |
|---|---|---|
| --days N | Lookback period in days | 7 |
| --today | Shorthand for --days 1 | — |
| --turns | Show per-turn detail, not just session aggregates | — |
| --commits | Correlate sessions with git commits | — |
| --tips | Show optimization tips based on your usage | — |
| --json | Output structured JSON instead of formatted terminal text | — |
| --quiet | Suppress non-essential output | — |
Examples
Default (7-day summary)
npx promptreports-cliFastest way to see your AI spend.
Today only
npx promptreports-cli --todayJust today's sessions — useful mid-day.
30-day view
npx promptreports-cli --days 30Monthly burn-rate check.
Per-turn detail
npx promptreports-cli --turnsDrill into individual turns — find the one that cost $2.40.
With optimization tips
npx promptreports-cli --tipsGet recommendations tailored to your actual usage.
Machine-readable
npx promptreports-cli --jsonPipe into jq, grep, or a dashboard.
Output
A formatted terminal report with 4 sections: aggregate summary box, top consumers table, token breakdown, and optimization suggestions.
┌─ CLAUDE TOKEN TRACKER — Usage Analysis ──────────────────┐
│ Period: last 7 days │
│ Sessions: 5, Messages: 87, Tokens: 456.2K, Cost: $4.23 │
│ Cache hit: 34.5% (saved $0.45) │
└───────────────────────────────────────────────────────────┘
TOP CONSUMERS (5)
Date Tokens Msgs Duration Cost
2026-04-18 156.7K 23 47m $1.45
2026-04-17 98.4K 18 32m $0.89
TOKEN BREAKDOWN
Output tokens 67% ████████████████░░░░░
Input tokens 22% █████░░░░░░░░░░░░░░░░
Cache write 8% █░░░░░░░░░░░░░░░░░░░░
Cache read 3% ░░░░░░░░░░░░░░░░░░░░░
SUGGESTIONS
→ 3 sessions exceed 30 messages. Summarize at message 15-20.
→ Cache hit rate low (34%). Structure prompts to reuse context.
→ Opus used 78% — try sonnet for simple edits.What it reads and writes
Reads
- ~/.claude/projects/**/*.jsonl
Writes
- .claude/research/token-stats-{date}.json (only with --json)
Free vs Pro usage
Free tier
- Check your AI spend daily — free forever
- Spot expensive sessions before the bill arrives
- Share output with teammates to set team norms
Pro tier
Upgrade- Auto-push summaries to a team dashboard for manager visibility
- Set cost thresholds and trigger Slack alerts when exceeded
- Compare cost-per-feature across engineers using shared tags
- Export to CSV for finance reconciliation
Pro tips
- Run it at end of day to set tomorrow's goals
- Pipe to jq for custom reports: `npx promptreports-cli --json | jq '.sessions[] | select(.cost > 1)'`
- Add to your shell startup so you see it every new terminal