codex-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/codex-token-heatmap.js"></script>
<codex-token-heatmap user="YOUR_GITHUB_USERNAME" palette="harbor"></codex-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

~/.codex/

→

Cloud

Supabase Storage

→

Your Website

<codex-token-heatmap>

The flow

sync Reads your local Codex rollout token events, aggregates counts, uploads a small 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 a small JSON file 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:

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

Color palettes

The preview palette is harbor. Pick a different one with the palette attribute:

<codex-token-heatmap user="you" palette="sky"></codex-token-heatmap>

Or define your own with CSS custom properties:

codex-token-heatmap {
  --cth-cell-l1: #e6f2fb;
  --cth-cell-l2: #c6def0;
  --cth-cell-l3: #8fbddd;
  --cth-cell-l4: #4f94bf;
}

Sizing

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

codex-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 --codex      # export Codex data
npx claude-count-tokens export -o out.json  # custom output path

What gets counted

The widget reads local Codex rollout token events from ~/.codex/. For each response, it sums:

Type	What it is
Input	tokens in your prompt
Output	tokens Codex generated
Models	token totals grouped by the Codex model used
Time	daily, hourly, and monthly totals for the heatmap

This counts Codex usage from local rollout token events on your machine.

Requirements

Node.js 18+
Codex installed and used locally (creates ~/.codex/ data)
macOS for auto-sync (Linux users can use a cron job instead)