tokenmaxxing by enqualia.io

Render dark, glassy posters of your Claude Code usage from local transcript files. 100% offline — nothing leaves your machine.

Two PNGs per run:

• Daily 5-minute lines — one row per calendar day, 288 bars per row (5-min resolution), with per-day active-hour counts and a 14-day average.
• Rolling 24h windows — newest 24h at the bottom ending at "now", older windows above. Great for "show me the last week of work".

Install

pipx install tokenmaxxing

Or with regular pip:

pip install tokenmaxxing

Requires Python 3.10+. Pulls in matplotlib and numpy.

Usage

tokenmaxxing --days 14 --metric messages
tokenmaxxing --days 7  --metric tokens
tokenmaxxing --days 5  --metric assistant

This writes tokenmaxxing_daily_5min.png and tokenmaxxing_rolling_24h.png into the current directory.

Flags

Flag	Default	Meaning
--days N	14	How many days of history to render.
--metric	messages	One of messages, tokens, assistant.
--project SUBSTR	""	Only count transcripts whose project-dir name contains this substring.
--root PATH	~/.claude/projects	Where Claude Code's JSONL transcripts live.
--png BASE	tokenmaxxing.png	Output base path. Two files are written: <base>_daily_5min.png and <base>_rolling_24h.png.
--min-per-hour N	metric-dependent	Threshold for an hour to count as "active". Filters out background harness pings. Defaults: messages=5, assistant=3, tokens=2000.
--watermark TEXT	tokenmaxxing	Watermark in the corner. Pass "" to hide.
--style	glass	glass (default, branded dark) or classic (plain matplotlib).

What data does it read?

Only ~/.claude/projects/**/*.jsonl — the transcript files Claude Code writes locally for every session. From each line it touches three fields:

• timestamp (ISO 8601)
• type ("user", "assistant", …)
• message.usage.output_tokens (only when --metric tokens)

No message content, file paths, or project names are read for the rendering — they exist on disk but the script does not parse them. No network calls, no API keys, no credentials.

"Active hours" definition

For each hour, the script collapses 5-min buckets into a single hourly value. An hour counts as active if the value meets --min-per-hour. Then a forgiving pass fills runs of ≤2 inactive hours that sit between two active hours — short breaks within a session still count. This avoids the "I worked 9am–11pm but took a 45-min lunch" being scored as two separate spans.

The total active-hour count per day appears at the right edge of each row, and an average across the rendered days appears in the header.

Examples

# Last month, by output tokens
tokenmaxxing --days 30 --metric tokens

# Just one project
tokenmaxxing --days 14 --project mycoolapp

# Hide the watermark for a clean export
tokenmaxxing --days 14 --watermark ""

Why these posters look the way they do

The renderer doesn't use imshow or any of matplotlib's built-in heatmap helpers — every panel, bar, gradient, and chip is drawn as primitives on a transparent axes, then composed over a warm radial-gradient background. Layout is inch-anchored so spacing stays correct across day counts.

License

MIT. See LICENSE.