AI Heatmap

GitHub-style heatmap for your AI usage costs. Powered by ccusage + react-activity-calendar.

Quick Start

curl -sS https://webi.sh/node | sh  # Node.js (includes npx)
curl -sS https://webi.sh/gh | sh    # GitHub CLI
gh auth login

# npx --yes ai-heatmap@latest delete
npx --yes clear-npx-cache && npx --yes ai-heatmap@latest init

USER=$(gh api user -q .login)
open "https://${USER}.github.io/${USER}-ai-heatmap/heatmap.svg"

npx --yes clear-npx-cache && npx --yes ai-heatmap@latest deploy

USER=$(gh api user -q .login)
open "https://${USER}-ai-heatmap.vercel.app/api/heatmap?colorScheme=dark"

Preview

Variations

<!-- Dark mode with full stats -->
![](https://{user}-ai-heatmap.vercel.app/api/heatmap?colorScheme=dark)

<!-- Blue theme, heatmap + stats only -->
![](https://{user}-ai-heatmap.vercel.app/api/heatmap?theme=blue&weekday=false)

<!-- Heatmap only (clean embed) -->
![](https://{user}-ai-heatmap.vercel.app/api/heatmap?stats=false&weekday=false)

<!-- Custom date range -->
![](https://{user}-ai-heatmap.vercel.app/api/heatmap?start=2026-01-01&end=2026-02-18)

SVG API (Vercel Only)

Deploy this repo to Vercel for a dynamic SVG endpoint. This is Vercel-only — GitHub Pages does not support serverless API routes.

Embed it in any README:

![AI Heatmap](https://{user}}-ai-heatmap.vercel.app/api/heatmap)

The SVG is generated on each request from public/data.json, so you can control the output with query parameters.

SVG API Options

Parameter	Default	Description
colorScheme	light	Color scheme: light, dark
theme	same as colorScheme	Theme override: light, dark, blue, orange, pink
blockSize	16	Size of each day block in pixels
blockMargin	4	Gap between blocks in pixels
blockRadius	3	Border radius of blocks in pixels
bg	auto	Background color (e.g. %23ffffff). Auto: transparent (light) / #0d1117 (dark)
textColor	auto	Text color. Auto: #24292f (light) / #c9d1d9 (dark)
start	-	Filter start date (YYYY-MM-DD)
end	-	Filter end date (YYYY-MM-DD)
stats	true	Show stats section (daily avg, weekly avg, peak, active days)
weekday	true	Show average-by-weekday bar chart

SVG API Examples

# Default light theme with all sections
/api/heatmap

# Dark theme
/api/heatmap?colorScheme=dark

# Pink theme, heatmap only
/api/heatmap?theme=pink&stats=false&weekday=false

# Custom block size
/api/heatmap?blockSize=12&blockMargin=3&blockRadius=2

# Date range filter
/api/heatmap?start=2026-01-01&end=2026-02-18

GitHub Pages (Interactive + Static SVG)

The interactive version with tooltips is deployed via GitHub Pages. Tooltips show cost, tokens, cache hit rate, and per-model breakdown.

A static SVG (heatmap.svg) is also generated during build. You can embed it as an image:

![AI Heatmap](https://{user}.github.io/{user}-ai-heatmap/heatmap.svg)

Static SVG is pre-generated at build time. For real-time rendering, use the Vercel SVG API.

GitHub Pages Options

All options are controlled via query string:

https://{user}.github.io/{user}-ai-heatmap/?colorScheme=dark&blockSize=14

Parameter	Default	Description
colorScheme	light	Color scheme: light, dark
blockSize	12	Size of each day block in pixels
blockMargin	3	Gap between blocks in pixels
blockRadius	2	Border radius of blocks in pixels
fontSize	12	Font size in pixels
hideColorLegend	false	Hide the color legend
hideMonthLabels	false	Hide month labels
hideTotalCount	false	Hide total count label
showWeekdayLabels	true	Show weekday labels (Mon, Wed, Fri)
weekStart	0	First day of week (0 = Sunday, 1 = Monday)
start	-	Filter start date (YYYY-MM-DD)
end	-	Filter end date (YYYY-MM-DD)

Available Themes (SVG API)

Theme	Colors
light	#ebedf0 #c6e48b #7bc96f #239a3b #196127
dark	#161b22 #0e4429 #006d32 #26a641 #39d353
blue	#ebedf0 #c0ddf9 #73b3f3 #3886e1 #1b4f91
orange	#ebedf0 #ffdf80 #ffa742 #e87d2f #ac5219
pink	#ebedf0 #ffc0cb #ff69b4 #ff1493 #c71585

Configuration

https://{user}.github.io/{user}-ai-heatmap/heatmap.svg

Customize the static SVG output by editing heatmap.config.json in the project root:

{
  "colorScheme": "dark",
  "theme": "",
  "blockSize": 16,
  "blockMargin": 4,
  "blockRadius": 3,
  "bg": "",
  "textColor": "",
  "start": "",
  "end": "",
  "stats": true,
  "weekday": true
}

This config is used by npm run generate:svg to build public/heatmap.svg. Empty strings ("") use auto defaults.

For the Vercel dynamic API, use query parameters instead (they override config).

Data Update

ccusage reads Claude Code usage logs from your local machine, so data must be generated locally and pushed to the repo.

npx ai-heatmap update

For automated updates, use a local cron job or macOS LaunchAgent:

CLAUDE_CODE_OAUTH_TOKEN=sk-ant-xxx
GH_TOKEN=ghp_xxx

0 0 * * * npx --yes clear-npx-cache && npx --yes ai-heatmap@latest update

npx: not found? cron uses a minimal PATH. Fix with:

# Find npx path
which npx   # e.g. /home/user/.local/bin/npx

# Use full path in cron
0 0 * * * PATH=$HOME/.local/bin:$PATH npx --yes clear-npx-cache && PATH=$HOME/.local/bin:$PATH npx --yes ai-heatmap@latest update

Upgrade

To use the latest version of ai-heatmap:

npx --yes clear-npx-cache && npx --yes ai-heatmap@latest update

Still running an old version? npx caches packages locally. If the update command behaves unexpectedly after a release, clear the cache:

npx --yes clear-npx-cache
npx --yes ai-heatmap@latest update

Deployment

npm publish

GitHub Pages

1. Enable GitHub Pages (Settings > Pages > Source: GitHub Actions)
2. Push data.json to main to trigger the first deploy
3. Manual deploy: Actions tab > "Deploy AI Heatmap" > "Run workflow"

Vercel (SVG API)

npx --yes clear-npx-cache && npx --yes ai-heatmap@latest deploy

Or manually:

1. Import this repo on vercel.com
2. Deploy (zero config — vercel.json included)
3. Make public: Project Settings > Deployment Protection > Vercel Authentication > OFF
4. Use the deployed URL for dynamic SVG embeds

Star History

Sponsor

If this project helps you, consider supporting it:

License

MIT License - see LICENSE file for details

Copyright (c) 2026 seunggabi

Author

seunggabi

• GitHub: @seunggabi
• Repository: ai-heatmap

---

Made with ❤️ using React, TypeScript, and Vite