pip install tokenmap
tokenmap

That's it. It reads your local data and renders a heatmap — plus an estimated cost breakdown — right in your terminal.

By default tokenmap includes your Claude Code data (and auto-detects any other installed tools), uses the dark-green theme, shows the cost breakdown, and stays terminal-only. Pass --export png (or svg/csv) when you want a shareable file.

Supported Tools

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

Install

pip install tokenmap

Requires Python 3.10+.

System Dependencies

For PNG export, you need Cairo installed:

# macOS
brew install cairo

# Ubuntu/Debian
sudo apt install libcairo2-dev

# Fedora
sudo dnf install cairo-devel

Usage

# Basic — Claude + any other auto-detected tools, cost breakdown, terminal only
tokenmap

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

# Pick tools (Claude is always included unless you pass --no-claude)
tokenmap --codex                 # Claude + Codex
tokenmap --no-claude             # everything detected EXCEPT Claude
tokenmap --no-claude --cursor    # Cursor only

# Filter by date
tokenmap --year 2025
tokenmap --since 2026-01-01 --until 2026-01-31
tokenmap --since 2026-05-01      # from a date through today

# Filter to one model (substring match)
tokenmap --model claude-opus-4-7
tokenmap --model opus            # every Opus variant

# Change the color theme (default is dark-green)
tokenmap --theme green

# Export a shareable file (off by default)
tokenmap --export png
tokenmap --export svg
tokenmap --export csv            # per-day token + cost rows
tokenmap --out ~/Desktop/my-ai-usage.png   # implies export, format from extension

# Copy PNG to clipboard (implies PNG export)
tokenmap --copy

# Dump raw stats as JSON (to stdout, or to a file with --out)
tokenmap --json
tokenmap --json --out stats.json

# Hide the cost breakdown (shown by default)
tokenmap --no-cost

# See all themes
tokenmap --list-themes

Themes

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

Options

Programmatic Usage

from tokenmap import aggregate_multi, render_terminal, render_svg, compute_stats
from tokenmap.types import RenderOptions

# Load data from all detected tools
panels = aggregate_multi()

# Render to terminal
render_terminal(panels, RenderOptions(theme="dark-green", user="myname"))

# Generate SVG
svg_string = render_svg(panels, RenderOptions(theme="dark-green", user="myname"))

# Access raw stats
for panel in panels:
    print(f"{panel.tool}: {panel.stats.total_tokens} tokens")

How It Works

tokenmap 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 + cost breakdown
4. Export (optional) — with --export, saves a high-res PNG/SVG with stats panel, or a CSV of per-day tokens + cost

Privacy

• All data is read locally from your filesystem
• Nothing is uploaded or transmitted
• Two optional network requests, both disable-able:
  • Cursor's API (to fetch your own usage CSV, using your local auth token) — with a local-only fallback that reads Cursor's state.vscdb on your machine when the API is unavailable.
  • A pricing lookup: a GET of LiteLLM's public pricing catalog (a static JSON file on GitHub) so cost estimates stay current for new models. No data about you is sent — it's a plain download, cached locally for 24 hours. Disable with --no-live-pricing; offline, tokenmap falls back to its built-in pricing table.

Attribution

This project is a Python port of tokenviz by Harsh Kedia. Original source: https://github.com/harshkedia177/tokenviz

Licensed under MIT. Original copyright retained.

License

MIT