A dark-themed CLI tool that visualizes your Claude Code token usage and costs by reading local conversation logs (~/.claude/projects/**/*.jsonl).
python3 -m pip install matplotlib tzdata && curl -s https://raw.githubusercontent.com/nhz-io/ccusage-plot/main/ccusage_plot.py | python3 - -p 7d --tz PST- Python 3.9+
matplotlibtzdata(Windows only — required when using--tz)
pip install matplotlib
# Windows users who need --tz:
pip install tzdatapython ccusage_plot.py [options]| Flag | Description | Default |
|---|---|---|
-p, --period |
Time period: 6h, 3d, 1w, 2m, etc. |
24h |
--all |
Plot all history | off |
--from |
Start date: YYYY-MM-DD or YYYY-MM-DD HH:MM |
none |
--to |
End date: YYYY-MM-DD or YYYY-MM-DD HH:MM |
none |
-o, --output |
Output PNG file path | ccusage_{period}.png |
--tz |
Timezone for x-axis and date parsing (PST, EST, UTC, Asia/Tokyo, etc.) |
UTC |
--highlight |
Highlight a daily time window, e.g. 5-11 or 5:00-11:30 |
none |
-v, --version |
Show version and exit | |
--update [PATH] |
Auto-update from GitHub. Optionally specify script path. |
You can specify what time window to plot in several ways:
| Flags | Meaning |
|---|---|
| (none) | Last 24 hours |
--all |
All history |
-p 7d |
Last 7 days from now |
--from 2025-03-20 |
From that date to now |
--from 2025-03-20 --to 2025-03-28 |
Explicit date range |
--from 2025-03-20 -p 7d |
7 days starting from March 20 |
--to 2025-03-28 -p 3d |
3 days ending March 28 |
Dates are parsed in the timezone specified by --tz (UTC if omitted).
# Last 24 hours (default)
python ccusage_plot.py
# All history
python ccusage_plot.py --all
# Last 7 days in Pacific time
python ccusage_plot.py -p 7d --tz PST
# Specific date range
python ccusage_plot.py --from 2025-03-20 --to 2025-03-28 --tz EST
# One week starting from a date
python ccusage_plot.py --from 2025-03-20 -p 1w
# Last 2 weeks, highlight working hours, custom output
python ccusage_plot.py -p 2w --tz EST --highlight 9-17 -o usage.png
# Last 3 months
python ccusage_plot.py -p 3mThe output PNG contains 9 panels:
- Input Tokens — per-segment bars + cumulative line
- Output Tokens — per-segment bars + cumulative line
- Cache Create Tokens — per-segment bars + cumulative line
- Cache Read Tokens — per-segment bars + cumulative line
- Total Tokens — per-segment bars + cumulative line
- Cost (USD) — per-segment bars + cumulative line
- Cost by Model — horizontal bar chart with per-model totals
- Token Breakdown — horizontal bar chart by token category
- Session Burn Rate — full-width EMA trend lines per token type with model-colored session dots, behavioral shift annotations, rate limit markers, and window boundaries
Time segments are auto-sized to maintain consistent bar density (~120 bars), snapping to clean intervals (1min, 5min, 15min, 1h, 4h, 12h, 1d, 1w, 30d).
Cost estimation uses published pricing for:
- Opus: 4.7, 4.6, 4.5, 4.1, 4, 3
- Sonnet: 4.6, 4.5, 4, 3.7, 3.5
- Haiku: 4.5, 3.5, 3
Cache-write tokens are split into 5-minute and 1-hour TTL buckets (Anthropic charges 1.25× base input for 5m writes vs 2× for 1h writes). The split is read from usage.cache_creation.ephemeral_5m_input_tokens / ephemeral_1h_input_tokens; legacy records without the nested split are charged at the cheaper 5m rate as a conservative undercount.
Unknown models fall back to Opus 4.7 pricing — overcharging an unknown haiku is loud and visible in the cost panel; silently undercharging a future opus variant at sonnet rates would be a quiet 5× miss.
MIT