--- title: >- Thermal — Contribution Heatmap & Token Accounting for AI Coding Tools — by Jad Madi (@jadmadi) description: >- Terminal heatmap, streaks, tokens, and cost across 14 AI coding environments. Thermal reads the session data your agents already wrote locally. One static Go binary, zero config, zero telemetry. href: /projects/thermal/ author: Jad Madi --- # Thermal — Contribution Heatmap & Token Accounting for AI Coding Tools Terminal heatmap, streaks, tokens, and cost across 14 AI coding environments. Thermal reads the session data your agents already wrote locally. One static Go binary, zero config, zero telemetry. - **Website**: https://jadmadi.net/projects/thermal/ - **Repository**: https://github.com/jadmadi/thermal - **License**: GNU AGPL-3.0 (Community Edition) / Commercial Enterprise License - **Version**: v0.12.0 ## Quickstart Install Thermal with a single command: ```bash curl -fsSL https://jadmadi.net/thermal/install.sh | sh ``` Or via Homebrew: ```bash brew install jadmadi/tap/thermal ``` Or build from source with Go: ```bash go install github.com/jadmadi/thermal/cmd/thermal@latest ``` ## Supported Tools Thermal automatically ingests activity and disjoint token metrics from 14 AI coding environments: | Tool | Category | Token Telemetry | Project Attribution | | :--- | :--- | :--- | :--- | | **Devin** | Token Warrior | Input, Output, Cache Read/Write | Working directory | | **OpenCode** | Token Warrior | Input, Output, Reasoning, Cache Read/Write | Session directory / git worktree | | **MiMoCode** | Token Warrior | Input, Output, Reasoning, Cache Read/Write | Session directory | | **Codex** | Token Warrior | Input, Output, Reasoning, Cache Read/Write | Thread working directory | | **codewhale** | Token Warrior | Total tokens, Recorded USD cost | Session workspace | | **ZCode** | Token Warrior | Input, Output, Cache Read | Working directory | | **Grok** | Token Warrior | Input, Output, Reasoning, Cache Read | Git root directory | | **Claude Code** | Token Warrior | Input, Output, Cache Read/Write | Per-message working directory | | **DeepSeek (DSH)** | Token Warrior | Input, Output, Cache Read/Write | Identity current working directory | | **Nous Hermes** | Token Warrior | Input, Output, Reasoning, Cache Read/Write | Session working directory | | **Muse** | Activity Hunter | Prompt & turn counts | Session index | | **Droid** | Activity Hunter | Turn & message counts | Message logs | | **command-code** | Activity Hunter | Message counts, Model distributions | Workspace directory | | **Agy** | Activity Hunter | Step activity, Model selections | CLI session logs | ## Core Capabilities ### Terminal Heatmaps & Streaks Visualizes daily activity and streak continuity directly in your terminal using ANSI 256-color heat ramps. Computes current streak, longest streak, and active days across all 14 tools. ### Disjoint Token Accounting All token types (Input, Output, Reasoning, CacheRead, CacheWrite) are strictly disjoint and sum to total volume. Nested structures from tools are automatically subtracted during loader ingestion. ### Workload Replay & Capacity Planning Replay recorded daily token distributions against commercial subscription ceilings (Claude Pro, Claude Max, ChatGPT Plus/Pro, Cursor Pro) with PASS/DEGRADED/FAIL verdicts and monthly cost deltas. ### Interactive TUI Dashboard Fullscreen Bubble Tea terminal interface with smooth keyboard navigation across Leaderboard, Projects, Models, Mix, and Trends views. ### Token Yield Telemetry Evaluates code generation productivity from git diffs and commits. Calculates Token Yield (tokens burned per net line of code added) with efficiency classification ratings. ### Verifiable Work Receipts Parses test execution (go test, pytest, cargo test, npm test) and linter proofs into 3-tier confidence classification with zero prompt or code privacy leakage. ### High-Density FinOps Grid Responsive 9-box Bubble Tea / Lip Gloss terminal grid decomposing agent activity across Coding, Debugging, Testing, and Exploration, while tracking prompt cache savings. ### Zero Network Telemetry 100% local operation: scans local databases and session directories in strictly read-only mode (mode=ro). Zero network calls, zero daemons, zero external telemetry. ## Common CLI Invocations | Command | Description | Category | | :--- | :--- | :--- | | `thermal` | Render contribution leaderboard and heatmaps across all discovered AI coding tools | core | | `thermal dashboard` | Interactive fullscreen Bubble Tea Terminal User Interface (TUI) | tui | | `thermal opencode | claude | devin | codex` | Inspect specific tool activity, token breakdown, and historical heatmaps | core | | `thermal projects` | Breakdown usage, token spend, and activity by repository and project | analytics | | `thermal models` | Model usage distribution and catalog pricing breakdown | analytics | | `thermal mix --chart` | Analytics, workload mix ratios, and trend charts | analytics | | `thermal stats --dense` | High-density 9-box terminal FinOps grid with prompt cache savings | analytics | | `thermal replay --against "Claude Pro"` | Replay historical workload against commercial subscription limits and quotas | cost | | `thermal yield --sort lines` | Code generation token yield and net line efficiency ratings | verification | | `thermal receipt --sort verified` | Verifiable work outcome proofs (test passes, linter runs) classification | verification | | `thermal audit` | Local environment health diagnostic, SQLite permissions, and mmap status | system | | `thermal share` | Generate stateless zero-database streak share card URL | system | | `thermal serve --open` | Embedded local web dashboard with zero cloud tracking on localhost | system | | `thermal upgrade` | Atomic in-place self-update check against latest GitHub Release | system | ## Frequently Asked Questions ### How does Thermal collect data without a daemon or API keys? Thermal runs strictly on-demand. When executed, it scans local session directories and SQLite databases that your AI tools already store on disk (such as ~/.claude/, ~/.codex/, ~/.opencode/). It opens files in strictly read-only mode and performs no network requests. ### What is disjoint token accounting? Different AI tools report tokens inconsistently (some bundle cache reads inside input, others report reasoning separately). Thermal normalizes and un-nests all token types into strictly mutually exclusive categories: Input, Output, Reasoning, CacheRead, and CacheWrite. They always sum precisely to total tokens. ### What does "thermal replay" do? It replays your recorded historical daily token burn against commercial subscription caps (like Claude Pro, Claude Max, ChatGPT Plus/Pro) to tell you whether your actual workload would fit within rate limits or if pay-as-you-go API is more cost-effective. ### How does licensing work? Thermal is dual-licensed: Free for personal and community use under the GNU AGPL-3.0, and available under a Commercial Enterprise License for corporate environments that require proprietary integration or exemption from AGPL provisions. ## Links & Resources - Interactive Project Page: https://jadmadi.net/projects/thermal/ - Video Walkthrough (YouTube): https://www.youtube.com/watch?v=QN7GMcJCEXU - GitHub Repository: https://github.com/jadmadi/thermal - Releases: https://github.com/jadmadi/thermal/releases - Author: [Jad Madi](https://jadmadi.net) ([@jadmadi](https://x.com/jadmadi))