clanker-analytics 0.2.5

AI coding tool token analytics powered by DuckDB

clanker-analytics

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.

Install

uv tool install clanker-analytics

Or run without installing:

uvx clanker-analytics

Usage

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

Cache rate regime detection

Worried your cache hit rate dropped? --regime auto-detects statistically significant changes using Welch's t-test:

clanker-analytics --regime --since 30d --tool claude

Finds the optimal changepoint, shows before/after means with z-score and p-value, and tells you the odds of it being random. Works across all tools or filtered to one.

How it works

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.

Columns

• 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

API cost calculation

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

Environmental impact estimates

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.

Chart colors

Brand colors used in --chart / --share output:

Tool	Color	Source
Claude Code	#d97757	Anthropic brand guidelines
Codex	#10a37f	OpenAI brand
Gemini	#4285f4	Google brand

Requirements

Python 3.13+, DuckDB 1.5+, matplotlib 3.9+.

Tested on Linux, macOS, and Windows (including WSL data auto-discovery).