claude-usage — 90-day heatmap for Claude Code

~ — bash

$ bash ~/.claude/claude-usage.sh Claude Usage — last 90 days W2 W3 W4 W5 W6 W7 W8 W9 W10W11W12W13W14 Mo ░ ░ ░ ░ ▒ ▒ ▒ ▓ ▓ █ █ Tu ░ ░ ░ ▒ ▒ ▒ ▓ ▓ █ ▲ We ░ ░ ░ ▒ ▒ ▓ ▓ █ ▲ Th ░ ░ ░ ▒ ▒ ▓ █ █ ▲ Fr ░ ░ ▒ ▒ ▒ ▓ ▓ █ Sa ░ ░ ▒ ▒ ▓ █ █ Su ░ ░ ▒ ▓ █ █ ▼ Legend: ░low ▒mod ▓heavy █max ▲5hr≥95% ▼wk≥95% Last 90 days: 121981 turns | 418.6M tokens | 1038 sessions Peak day: 2026-04-02 — 90.5M tokens By project: ClauDe/orcaPatch █████░░░░░░░░░░░ 31% ClauDe/gridfinity ███░░░░░░░░░░░░░ 20% other ████░░░░░░░░░░░░ 49% By model: opus ███████████░░░░░ 73% sonnet ███░░░░░░░░░░░░░ 21% haiku █░░░░░░░░░░░░░░░ 6% Rate limits: ▲ 4 days with 5hr spike ▼ 1 week at weekly limit

What it tracks

13-week heatmap

GitHub-style calendar grid, Monday-anchored. Intensity is rank-based quartiles so one monster day doesn't flatten everything else.

Token breakdown

Input + cache creation + output, summed across the window. Cache reads excluded — they're reuse, not spend.

By project

Derived from cwd in each transcript entry. No configuration needed — it figures out what you were working on.

By model

Opus vs. sonnet vs. haiku token split at a glance. Useful for understanding where your compute is going.

Rate limit markers

Red ▲ marks days with 5-hour spikes (≥95%). Magenta ▼ marks weeks at weekly limit. Requires claude-statusline for data.

Fully local

Reads only ~/.claude/projects/ on your machine. No network calls, no auth, no data leaves your system.

Platform support

Platform	Status	Notes
macOS	YES	Native ANSI. Use `claude-usage.sh`.
Linux	YES	Native ANSI. Use `claude-usage.sh`.
Windows Terminal	YES	VT100 enabled by default. Use `claude-usage.ps1`.
VS Code terminal	YES	Full color support. Use `claude-usage.ps1`.
Windows cmd.exe	NO	No ANSI 256-color. Use Windows Terminal instead.

Install

# One-liner
curl -fsSL https://raw.githubusercontent.com/thereprocase/claude-usage/main/install.sh | bash

# Or manually
cp claude-usage.py ~/.claude/
cp claude-usage.sh ~/.claude/
chmod +x ~/.claude/claude-usage.sh

# Run
bash ~/.claude/claude-usage.sh

# One-liner (PowerShell)
irm https://raw.githubusercontent.com/thereprocase/claude-usage/main/install.ps1 | iex

# Or manually
Copy-Item claude-usage.py  $HOME\.claude\
Copy-Item claude-usage.ps1 $HOME\.claude\

# Run
pwsh $HOME\.claude\claude-usage.ps1

# Add to ~/.claude/settings.json
{
  "slash_commands": {
    "usage-graph": {
      "description": "Show 90-day Claude usage heatmap",
      "command": "bash ~/.claude/claude-usage.sh"
    }
  }
}

# Windows: replace command with
# "pwsh $HOME\\.claude\\claude-usage.ps1"

# Then in any Claude Code session:
/usage-graph