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