Token usage analytics for AI coding tools. Reads local session logs and shows per-project breakdowns using DuckDB.
Supports Claude Code, Codex, and Gemini CLI.
Worried your cache hit rate dropped? --regime auto-detects statistically significant changes using Welch's t-test: clanker-analytics --regime --since 30d --tool claude
uv tool install clanker-analytics
Or run without installing:
uvx clanker-analytics
clanker-analytics # 7-day chart (default)
clanker-analytics --since 24h # last 24 hours (also: 7d, 2w, 2026-03-01)
clanker-analytics --share # chart + copy to clipboard + open X
clanker-analytics --table # tabular view
clanker-analytics --table --by date # table grouped by date (also: model, session)
clanker-analytics --regime # detect cache rate regime changes
clanker-analytics --tool claude # Claude Code only (also: codex, gemini)
clanker-analytics --refresh # force cache rebuild
clanker-analytics --debug-timing # print cache decisions and stage timings
clanker-analytics --profile # print a cProfile summary to stderr
clanker-analytics --sql "SELECT ..." # custom SQL against 'tokens' table
DuckDB reads session logs directly from ~/.claude/projects/, ~/.codex/sessions/, and ~/.gemini/tmp/ — no Python JSON parsing. Results are cached to ~/.cache/clanker-analytics/tokens.parquet (ZSTD compressed) with a per-file manifest at ~/.cache/clanker-analytics/tokens-meta.json.
The cache is incremental: unchanged source files are reused, changed files are re-read, and deleted files are removed from the cached table. A full rebuild only happens when the cache is missing, you pass --refresh, or the cache schema changes.
--debug-timing prints cache decisions and per-stage timings. --profile adds a Python cProfile summary; it is mainly useful for filesystem scanning and Python-side overhead, not DuckDB query execution time.
- total — all tokens processed (input + output + cache write + cache read)
- billable — total minus the 90% cache read discount
- output — output tokens only
- cache — cache read hits as % of input tokens
- api_cost — estimated cost at API rates
The api_cost and billable columns use published API pricing. Cache reads are 0.1x the input token price for all three providers:
| Input | Cache read | Cache write | Output | |
|---|---|---|---|---|
| Claude Sonnet | $3/MTok | $0.30/MTok | $3.75/MTok | $15/MTok |
| Claude Opus | $5/MTok | $0.50/MTok | $6.25/MTok | $25/MTok |
| GPT-5 | $1.25/MTok | $0.125/MTok | (auto) | $10/MTok |
| Gemini Flash | $0.15/MTok | $0.0375/MTok | (auto) | $0.60/MTok |
| Gemini 2.5 Pro | $1.25/MTok | $0.125/MTok | (auto) | $10/MTok |
| Gemini 3.1 Pro | $2/MTok | $0.50/MTok | (auto) | $12/MTok |
Sources: Anthropic pricing, OpenAI pricing, Google AI pricing
The --chart / --share output shows estimated environmental impact per million tokens:
| Metric | Per 1M tokens | Source |
|---|---|---|
| Electricity | 0.6 kWh | Epoch AI, arxiv:2505.09598 |
| Water | 1 liter | Li & Ren (2023), adjusted for modern models |
| CO2 | 90 g | Ritchie (2025) |
These are rough estimates — actual impact varies 10-100x depending on model, hardware, and data center location. No provider publishes official per-token figures.
Brand colors used in --chart / --share output:
| Tool | Color | Source |
|---|---|---|
| Claude Code | #d97757 |
Anthropic brand guidelines |
| Codex | #10a37f |
OpenAI brand |
| Gemini | #4285f4 |
Google brand |
Python 3.13+, DuckDB 1.5+, matplotlib 3.9+.
Tested on Linux, macOS, and Windows (including WSL data auto-discovery).