token-heatmap

GitHub-style terminal heatmap for your AI coding tool token usage.

Scans local logs from Claude Code and OpenAI Codex, shows per-day token consumption, model breakdown, and time-spent-coding stats. Single file, zero runtime dependencies.

Quick Start

# Download and run (requires Node.js 18+)
curl -sL https://raw.githubusercontent.com/zqchris/token-heatmap/main/token-heatmap.mjs -o token-heatmap.mjs
node token-heatmap.mjs

Or clone the repo:

git clone https://github.com/zqchris/token-heatmap.git
cd token-heatmap
node token-heatmap.mjs

What it looks like

  Claude Code

     Feb     Mar
 Mon ░ ░ ░ █ █
     ░ ░ ░ █ █
 Wed ░ ░ ░ █ █
     ░ ░ ░ █ █
 Fri ░ ░ ░ █
     ░ ░ █ ░
 Sun ░ ░ ░ ░

     Less ░ █ █ █ █ █ More

  Total Tokens:     900.1M  (in: 871.3M out: 28.8M)
  Active Days:      10/30 (33.3%)
  Longest Streak:   5 days

  Time Spent Coding with AI
  Sessions:          233
  Total Active:      38h 52m (1.6 days)
  Avg Session:       10m
  Longest Session:   5h 9m

  Top Models
  ████████████████████ claude-opus-4-6         833.3M (92.6%)
  ██░░░░░░░░░░░░░░░░░░ claude-haiku-4-5         66.1M (7.3%)

(actual output is colored)

Options

node token-heatmap.mjs [options]

  --claude       Show only Claude Code usage
  --codex        Show only Codex usage
  --days N       Number of days to show (default: 365)
  --json         Output as JSON
  -h, --help     Show help

Data Sources

Provider	Log Location
Claude Code (CLI)	~/.claude/projects/**/*.jsonl
Claude Desktop	~/Library/Application Support/Claude/local-agent-mode-sessions/
Codex	~/.codex/sessions/**/*.jsonl

All data is read locally. Nothing is sent anywhere.

Development

npm install
npm run dev          # run from source (uses tsx)
npm run build        # rebuild token-heatmap.mjs

License

MIT