GitHub-style heatmap for last 30 days of Claude Code tokens, powered by ccusage.
npm install ccusage-heat30A Node.js CLI tool built on top of ccusage with optional @ccusage/codex integration that generates GitHub-style heatmaps displaying the last 30 days of Claude Code token usage with extended visualization features and comprehensive analytics.
#### š New Features
- Desktop-ready SVG exports: --svg now defaults to your Desktop with a polished dashboard layout, interactive cell tooltips, and a dedicated billing summary banner.
- Adaptive color output: Detects 24-bit, 256-color, and monochrome terminals automatically, falling back to readable ASCII glyphs when colors are unavailable or --no-color is set.
- Top-five leaderboards: Cost tables now focus on the five spendiest days, always including today when usage exists, with model-level context and token breakdowns.
- Unified Claude + Codex heatmap: Codex usage is merged into the main grid, accompanied by matching Codex leaderboards and billing totals.
#### š§ Improvements
- Month labels stay aligned with the heatmap grid even on narrow terminals.
- Numeric columns in tables get wider padding so large token counts remain legible.
- Billing summary box centers inside the outer frame and reflects the cumulative Claude Code spend for the current billing cycle.
---
- š GitHub-style heatmap ā Shows combined Claude + Codex activity over the last 30 days, powered by ccusage and enhanced with @ccusage/codex when present.
- š° Multiple metrics ā Track tokens, cost, input tokens, or output tokens.
- šØ Terminal display ā Beautiful colored output with ANSI colors and a centered billing summary.
- š Professional SVG export ā Dashboard-style layout combining heatmap, statistics table, and billing summary.
- š Top-five usage tables ā Highlights the five costliest days for Claude (always) and Codex (when data exists), with per-model stats and today-aware inclusion.
- š¤ Codex usage mirror ā Adds a Codex top-five table (via @ccusage/codex) beneath the Claude leaderboard whenever Codex logs are detected.
- šµ Billing summary ā Prominently shows cumulative usage costs for the billing cycle.
- šÆ Centered layout ā Both terminal and SVG outputs feature properly centered content for professional presentation.
- āļø Customizable ā Configure week start day, timezone, and output options.
- Node.js version 20.19.4 or higher is required.
- The ccusage CLI (and optional @ccusage/codex companion) install automatically when using npx. Ensure both are accessible for dual Claude/Codex reporting.
- Permission to run CLI tools on your system.
``bash`
npx ccusage-heat30
`bash`
npm install -g ccusage-heat30
ccusage-heat30
`bash`
git clone
cd ccusage-heat30
npm install
node bin/cli.mjs
`bashDisplay combined Claude + Codex heatmap
ccusage-heat30
$3
bash
Save as SVG file
ccusage-heat30 --svg heatmap.svgSave to specific directory
ccusage-heat30 --svg ./assets/usage-heatmap.svgCombine with different metrics
ccusage-heat30 --metric cost --svg cost-analysis.svg
`When using the
option without specifying a file path, the SVG file is saved to your Desktop with the filename pattern cc-heatmap-YYYYMMDD.svg, where YYYYMMDD is the current date. The exported SVG includes interactive tooltips that display the date and corresponding usage value when hovering over heatmap cells in most SVG viewers.$3
`bash
Start week on Sunday (default: Monday)
ccusage-heat30 --week-start sunDisable colors (for terminal compatibility)
ccusage-heat30 --no-colorSpecify timezone (defaults to your system zone, passed through to the ccusage/@ccusage tools)
ccusage-heat30 --timezone "America/New_York"Claude-only (hide Codex)
ccusage-heat30 --source claudeCodex-only (hide Claude)
ccusage-heat30 --source codexCombine multiple options
ccusage-heat30 --metric cost --source claude --svg output.svg --week-start sun
`$3
When
is available (either locally installed or resolved via npx), the CLI automatically mirrors the Claude leaderboard with a Codex top-5 table using the same styling. It also stacks Codex metrics into the main heatmap so the cells reflect total cross-platform activity. The CLI now defaults to your system timezone when calling both analyzers, so same-day usage appears under the expected local date. Use npx @ccusage/codex@latest daily --json --by-model to verify Codex data collection and ensure your Codex logs live under ~/.codex/. You can toggle sources via --source, e.g. --source codex for Codex-only reports or --source claude to hide Codex rows while keeping combined heatmap available when set back to both.#### Tips for Codex reporting
-
@ccusage/codex reads session JSONL files from ~/.codex/projects/**/sessions/. Set CODEX_HOME if your logs live elsewhere.
- Codex CLI keeps appending to the session file that was opened first (Pacific Time). End or rotate sessions if you want a fresh date in your local timezone.
- Re-run npx @ccusage/codex@latest daily --timezone to see where the latest spend landed. Once Codex emits a new daily file, the combined heatmap and Codex top-five table update automatically.
- ccusage-heat30 auto-detects your system timezone; supply --timezone to override for both analyzers.#### Quick check for Codex data
1.
npx @ccusage/codex@latest daily --json --by-model --since $(date +%Y%m%d) --until $(date +%Y%m%d) to confirm today's records.
2. If the entry still shows yesterday, finish the active Codex session (or wait for Codex CLI to rotate the session file).
3. Run ccusage-heat30 --metric cost --source codex (append --timezone if you need to override the auto-detected zone).
Command Line Options
| Option | Description | Values | Default |
|----------------|-------------------------------|-----------------------------|----------|
|
--metric | Choose what metric to visualize | tokens, cost, input, output | tokens |
| --week-start | Set the first day of the week | sun, mon | mon |
| --svg | Export heatmap as SVG file | File path | - |
| --no-color | Disable terminal colors | - | - |
| --timezone | Timezone for usage data | Timezone string | System default |
| --source | Select data source | both, claude, codex | both |Sample Output
$3
`text
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā Claude + Codex usage ā
ā ā
ā Aug Sep ā
ā āāāāāāā āāāāāāā āāā āāā āāāāāāā āāāāāā āāāāāāā āāāāāāāā ā
āāāāāāāāāā āāāāāāāāā āāā āāā āāāāāāāā āāāāāāāā āāāāāāāā āāāāāāāā ā
āāāā āāā āāā āāā āāā āāā āāā āāāā āāāāāāāā āāā āāāā āāāāāā ā
āāāā āāā āāā āāā āāā āāā āāā āāā āāāāāāāā āāā āāā āāāāāā ā
āāāāāāāāāā āāāāāāāāā āāāāāāāāā āāāāāāāāā āāā āāā āāāāāāāā āāāāāāāā ā
ā āāāāāāā āāāāāāā āāāāāāā āāāāāāā āāā āāā āāāāāāā āāāāāāāā ā
ā ā
ā Top 5 Claude Code Days by cost: ā
ā āāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāāāāāāāāāā¬āāāāāāāāā¬āāāāāāāāāā¬āāāāāāāāāāāāā¬āāāāāāāāāāāāā ā
ā ā Date ā Models ā Input ā Output ā Total ā Cost (USD) ā ā
ā āāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāāāāāāāāāāā¼āāāāāāāāā¼āāāāāāāāāā¼āāāāāāāāāāāāā¼āāāāāāāāāāāāā¤ ā
ā ā 2025-09-17 ā claude-sonnet-4-20250514 ā 6,674 ā 56,496 ā 35,186,889 ā $16.6065 ā ā
ā ā 2025-09-16 ā claude-sonnet-4-20250514 ā 7,815 ā 54,873 ā 25,298,427 ā $14.3129 ā ā
ā ā 2025-09-18 ā claude-sonnet-4-20250514 ā 30,766 ā 35,870 ā 26,803,313 ā $14.6155 ā ā
ā ā 2025-09-11 ā claude-sonnet-4-20250514 ā 15,930 ā 105,669 ā 19,455,740 ā $13.5066 ā ā
ā ā 2025-09-15 ā claude-sonnet-4-20250514 ā 17,568 ā 12,420 ā 8,060,668 ā $5.0742 ā ā
ā āāāāāāāāāāāāāā“āāāāāāāāāāāāāāāāāāāāāāāāāāā“āāāāāāāāā“āāāāāāāāāā“āāāāāāāāāāāāā“āāāāāāāāāāāāā ā
ā ā
ā Top 5 Codex Days by cost: ā
ā āāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāā¬āāāāāāāāāā¬āāāāāāāāāāāāā¬āāāāāāāāāāāāā ā
ā ā Date ā Models ā Input ā Output ā Total ā Cost (USD) ā ā
ā āāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāā¼āāāāāāāāāā¼āāāāāāāāāāāāā¼āāāāāāāāāāāāā¤ ā
ā ā Sep 14, 2025 ā gpt-5-codex, gpt-5 ā 111,098,122 ā 228,068 ā 56,558,190 ā $10.6148 ā ā
ā ā Sep 15, 2025 ā gpt-5-codex, gpt-5 ā 41,326,259 ā 238,451 ā 21,720,550 ā $6.3410 ā ā
ā ā Sep 21, 2025 ā gpt-5-codex ā 16,867,099 ā 115,362 ā 8,835,581 ā $2.5427 ā ā
ā ā Sep 18, 2025 ā gpt-5 ā 9,081,428 ā 41,812 ā 4,663,912 ā $1.0790 ā ā
ā ā Sep 19, 2025 ā gpt-5 ā 1,091,427 ā 8,784 ā 584,563 ā $0.2055 ā ā
ā āāāāāāāāāāāāāāāā“āāāāāāāāāāāāāāāāāāāāā“āāāāāāāāāāāāāā“āāāāāāāāāā“āāāāāāāāāāāāā“āāāāāāāāāāāāā ā
ā ā
ā Legend: ā
ā Less - 2,901,706 - 8,399,564 - 13,441,088 - 25,298,427 - More ā
ā ā
ā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā
ā ā You have cumulatively used $97.0136 USD of Claude Code in this billing cycle. ā ā
ā ā You have cumulatively used $21.9594 USD of Codex in this billing cycle. ā ā
ā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
`$3
When exporting with
, you receive a comprehensive dashboard with the following characteristics:- Default save location is the Desktop with filename
cc-heatmap-YYYYMMDD.svg if no path is specified.
- Supports custom output paths to save SVG files in any directory.
- Left side features a GitHub-style heatmap with month/day labels and a color legend.
- Right side contains a professional table showing the top 5 usage days with detailed model information, sorted by cost.
- Bottom section highlights the billing summary with total cost.
- All elements are properly aligned and centered for a clean, professional look.
- Interactive tooltips appear when hovering over heatmap cells in most SVG viewers, showing the date and usage value.
- The SVG output is responsive and displays correctly across various viewers.Requirements
- Node.js 20.19.4 or higher
- ccusage (Claude) /
@ccusage/codex (Codex optional) - Available as npm dependencies or via npxHow It Works
1. Data Collection: Fetches usage data using the
ccusage CLI (and @ccusage/codex when available) for the last 30 days.
2. Grid Generation: Creates a GitHub-style 7ĆN grid representing days of the week.
3. Color Mapping: Applies color intensity based on usage quantiles.
4. Analytics Processing: Calculates top usage days and billing totals.
5. Terminal Rendering: Displays heatmap with ANSI colors and centered billing summary.
6. SVG Export: Generates a comprehensive dashboard with heatmap, table, and billing info.
7. Layout Optimization: Centers all content for professional presentation.Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Acknowledgments
This project is built upon and extends the ccusage project and consumes its scoped npm release
@ccusage/codex for Codex metrics, all licensed under the MIT License. Modifications and enhancements in this tool are also provided under the MIT License.Special thanks to these amazing open source projects that made this tool possible:
- ccusage by @ryoppippi ā The core project powering the
@ccusage/codex` CLI used for Claude Code usage data collection and analysis (MIT License).MIT License ā see LICENSE file for details.
---
Built for the Claude Code community š¤āØ
Made by Nitro with ā¤ļø in Edmonton.