ai-count-tokens

live preview

try a palette

made with by vitoria

three commands, then you're done

npx claude-count-tokens login

Upload your token data

npx claude-count-tokens sync

Auto-sync every hour

npx claude-count-tokens sync --install

Add two lines to your website

<script type="module" src="https://unpkg.com/claude-count-tokens/widget/ai-token-heatmap.js"></script>
<ai-token-heatmap user="YOUR_GITHUB_USERNAME" palette="siteDuo"></ai-token-heatmap>

Works with any site — plain HTML, Next.js, Astro, Hugo, Jekyll, WordPress. No build step, no dependencies.

New install vs update

If you're installing this for the first time, use the latest package explicitly:

npx claude-count-tokens@latest login
npx claude-count-tokens@latest sync
npx claude-count-tokens@latest sync --install

If you installed this a while ago, refresh the package and background sync so Codex and combined data are uploaded too:

npx claude-count-tokens@latest sync
npx claude-count-tokens@latest sync --install

Architecture

Your Mac

~/.claude/ + ~/.codex/

→

Cloud

Supabase Storage

→

Your Website

<ai-token-heatmap>

The flow

sync Reads local Claude and Codex usage sources, aggregates token counts, uploads one combined JSON file

auto-sync A background job on your Mac re-syncs every hour so your widget is always current

widget A self-contained web component that fetches your JSON and renders the heatmap

Privacy

Only aggregated token counts are synced to the cloud — no prompts, no code, no paths, no conversation content. The sync uploads small JSON files with daily/hourly/model totals. Everything else stays on your machine.

Dark mode

The widget automatically follows your site's theme. It detects dark mode from:

prefers-color-scheme (system preference)
class="dark" on <html> or <body>
data-theme="dark" on <html> or <body>

To force a specific theme:

<ai-token-heatmap user="you" theme="dark"></ai-token-heatmap>

Color palettes

The site palette is siteDuo. Pick a different one with the palette attribute:

<ai-token-heatmap user="you" palette="softDuo"></ai-token-heatmap>

Or define your own with CSS custom properties:

ai-token-heatmap {
  --cth-cell-l1: #dbebc7;
  --cth-cell-l2: #b8d69a;
  --cth-cell-l3: #8fbddd;
  --cth-cell-l4: #4f94bf;
}

Sizing

The widget fills its container by default. Customize with CSS:

ai-token-heatmap {
  max-width: 600px;     /* constrain width */
  --cth-cell-s: 10px;   /* cell size (default 13px) */
  --cth-cell-g: 2px;    /* gap (default 3px) */
  --cth-cell-r: 2px;    /* border radius (default 3px) */
}

Automatically shrinks on screens narrower than 700px.

CLI reference

# dashboard
npx claude-count-tokens                     # live dashboard on port 7890
npx claude-count-tokens --port 3000         # custom port
npx claude-count-tokens --days 90           # last 90 days only

# auth
npx claude-count-tokens login               # log in with GitHub
npx claude-count-tokens logout              # log out, clear credentials

# sync
npx claude-count-tokens sync                # upload token data to cloud
npx claude-count-tokens sync --install      # auto-sync every hour (macOS)
npx claude-count-tokens sync --uninstall    # remove auto-sync
npx claude-count-tokens sync --status       # check if auto-sync is running

# export
npx claude-count-tokens export              # export to ./claude-token-data.json
npx claude-count-tokens export --combined   # export combined data
npx claude-count-tokens export -o out.json  # custom output path

What gets counted

The widget combines local Claude and Codex usage sources. It currently includes:

Type	What it is
Claude Code	local Claude Code JSONL logs
Conductor	Conductor Claude API usage from this machine
Zed	local Zed thread token usage
Codex	local Codex rollout token events

This is the combined view; use the Claude or Codex pages when you want one product only.

Requirements

Node.js 18+
Claude Code and/or Codex installed and used locally
macOS for auto-sync (Linux users can use a cron job instead)