--- title: Thermal — Multi-agent terminal heatmap, token FinOps, workload replay simulator, and verifiable work receipt engine — by Jad Madi (@jadmadi) description: Multi-agent terminal heatmap, token FinOps, workload replay simulator, and verifiable work receipt engine for 14+ AI coding agents. Reads the local session data your agents already wrote. One static Go binary, zero config, zero telemetry. href: /project/thermal/ author: Jad Madi --- # Thermal — Multi-agent terminal heatmap, token FinOps, workload replay simulator, and verifiable work receipt engine Multi-agent terminal heatmap, token FinOps, workload replay simulator, and verifiable work receipt engine for 14+ AI coding agents. Reads the local session data your agents already wrote. One static Go binary, zero config, zero telemetry. - **Website**: https://jadmadi.net/project/thermal/ - **Repository**: https://github.com/jadmadi/thermal - **License**: GNU AGPL-3.0 (Community Edition) / Commercial Enterprise License - **Version**: v0.18.0 ## Quickstart Install Thermal with a single command: ```bash curl -fsSL https://jadmadi.net/thermal/install.sh | sh ``` 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/project/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: [@JadMadi](https://x.com/jadmadi)