tokenviz

Your AI coding stats, visualized.

A GitHub-style contribution heatmap that shows how much you actually use AI coding tools. One command. Auto-detected. Shareable.

npx tokenviz@latest

That's it. It reads your local data, renders a heatmap in your terminal, and exports a shareable PNG.

Single Tool View

Multi-Tool View

Supported Tools

| Tool | Data Source | What's Tracked | |------|-----------|----------------| | Claude Code | ~/.claude/stats-cache.json | Tokens, models, sessions, costs | | Codex CLI | ~/.codex/sessions/*.jsonl | Tokens, models, session durations | | OpenCode | ~/.local/share/opencode/ | Tokens, models, messages | | Cursor | Cursor API + local state.vscdb | Tokens, models, usage events |

tokenviz auto-detects which tools you have installed. No configuration needed.

Install

# Run directly (no install)
npx tokenviz@latest

# Run stats for a specific tool
npx tokenviz@latest --claude
npx tokenviz@latest --codex
npx tokenviz@latest --cursor
npx tokenviz@latest --opencode

# Or install globally
npm install -g tokenviz
tokenviz

Requires Node.js 18+.

What You Get

Terminal Heatmap

A full-color contribution grid right in your terminal, with:

• Token usage breakdown (input / output / total)
• Most used model (all-time + last 30 days)
• Current & longest streaks
• Peak coding hour & busiest day
• Average session length
• Per-tool usage panels

Shareable PNG/SVG

Automatically exports a high-quality image you can share on Twitter, LinkedIn, your blog, or anywhere.

tokenviz --user yourname              # PNG with your name
tokenviz --user yourname --export svg # SVG export
tokenviz --user yourname --copy       # PNG + copy to clipboard

Usage

# Basic — auto-detect all tools, export PNG
tokenviz

# Add your name to the heatmap
tokenviz --user yourname

# Filter to a specific tool
tokenviz --claude
tokenviz --codex
tokenviz --cursor
tokenviz --opencode

# Filter to a specific year
tokenviz --year 2025

# Change the color theme
tokenviz --theme dark-green

# Export as SVG instead of PNG
tokenviz --export svg

# Custom output path
tokenviz --out ~/Desktop/my-ai-usage.png

# Terminal only, no file export
tokenviz --no-export

# Copy PNG to clipboard (macOS/Linux/Windows)
tokenviz --copy

# Dump raw stats as JSON (for scripting)
tokenviz --json

# See all themes
tokenviz --list-themes

Themes

10 built-in themes — 5 light, 5 dark:

| Dark | Light | |------|-------| | dark-ember | green (default) | | dark-green | purple | | dark-purple | blue | | dark-blue | amber | | dark-mono | mono |

tokenviz --theme dark-purple
tokenviz --theme amber

Options

| Flag | Description | Default | |------|-------------|---------| | --user <name> | Username shown on the heatmap | — | | --claude | Include only Claude Code data | — | | --codex | Include only Codex data | — | | --opencode | Include only OpenCode data | — | | --cursor | Include only Cursor data | — | | --theme <name> | Color theme | green | | --export <fmt> | Export format: png or svg | png | | --no-export | Skip file export, terminal only | — | | --out <path> | Custom output file path | tokenviz.png | | --copy | Copy PNG to clipboard after export | — | | --year <year> | Filter to a specific year | last 365 days | | --json | Output raw stats as JSON | — | | --list-themes | Show all available themes | — |

How It Works

tokenviz reads locally stored data from your AI coding tools. It never sends data anywhere — everything stays on your machine.

1. Detect — scans for installed tool data directories
2. Aggregate — merges token usage, sessions, and model stats across tools
3. Render — generates a terminal heatmap + exportable image
4. Export — saves a high-res PNG/SVG with stats panel

Privacy

• All data is read locally from your filesystem
• Nothing is uploaded or transmitted
• The only network request is Cursor's API (to fetch your own usage CSV, using your local auth token) — and even that's optional with a local fallback

FAQ

Q: I don't see any data? Make sure you've actually used one of the supported tools. tokenviz reads from the default data locations — if you've customized paths, set the environment variable:

• CLAUDE_CONFIG_DIR for Claude Code
• CODEX_HOME for Codex CLI
• OPENCODE_DATA_DIR for OpenCode
• CURSOR_STATE_DB_PATH or CURSOR_CONFIG_DIR for Cursor

Q: Can I use this in CI/scripts? Yes — tokenviz --json outputs machine-readable JSON.

Q: The Cursor data seems low? If the API fetch fails (auth issues), tokenviz falls back to local line-count tracking which estimates tokens. The API-based data is more accurate.

Contributing

PRs welcome! The codebase is TypeScript with ESM modules.

git clone https://github.com/harshkedia177/tokenviz.git
cd tokenviz
npm install
npm run dev    # watch mode
node dist/bin.js --list-themes

License

MIT