thermal

About thermal

This large README is shown as a plain-text preview. Read the full README at the source

<p align="center">
  <img src="assets/thermal.webp" alt="Thermal Gopher Mascot" width="160" />
</p>

# Thermal

[![Go Report Card](https://goreportcard.com/badge/github.com/jadmadi/thermal)](https://goreportcard.com/report/github.com/jadmadi/thermal)
[![PkgGoDev](https://pkg.go.dev/badge/github.com/jadmadi/thermal)](https://pkg.go.dev/github.com/jadmadi/thermal)
[![CI](https://github.com/jadmadi/thermal/actions/workflows/ci.yml/badge.svg)](https://github.com/jadmadi/thermal/actions/workflows/ci.yml)
[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL_3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![Dual License: Commercial](https://img.shields.io/badge/Dual_License-Commercial-green.svg)](DUAL-LICENSE.md)
[![Governance: Solo Authority](https://img.shields.io/badge/Governance-Solo_Authority-purple.svg)](GOVERNANCE.md)
[![SLSA Level 3](https://slsa.dev/images/gh-badge-level3.svg)](https://slsa.dev)

> Multi-agent terminal heatmap, token FinOps, workload replay simulator, and verifiable work receipt engine for 15+ AI coding agents.

```bash
# Automated install (Linux & macOS)
curl -fsSL https://jadmadi.net/thermal/install.sh | sh

# Homebrew (macOS & Linux)
brew install jadmadi/tap/thermal

# Go toolchain
go install github.com/jadmadi/thermal/cmd/thermal@latest
```

Unlike `git log`, which only shows committed code, Thermal shows what your agents actually burned: tokens, cost, and streaks across tools, even when nothing got committed. All local, zero cloud telemetry, and under 10ms execution.

![Thermal leaderboard](assets/leaderboard.webp)

## Supported Tools

| Tool               | Data Source                                        | Metrics                                       |
|--------------------|----------------------------------------------------|-----------------------------------------------|
| **Devin**          | SQLite DB (sessions + message_nodes)               | Token usage, sessions, cost                   |
| **OpenCode**       | SQLite DB (v1 and v2 storage)                      | Token usage, sessions, cost                   |
| **MiMoCode**       | SQLite DB                                          | Token usage, sessions, cost                   |
| **Codex**          | SQLite DB (state_5.sqlite) + rollout JSONL         | Token usage, sessions, model/source breakdown |
| **codewhale**      | JSON sessions                                      | Token usage, sessions, cost                   |
| **ZCode**          | SQLite DB (`model_usage` telemetry)                | Token usage, sessions, model/agent breakdown  |
| **Grok**           | JSONL session logs (`turn_completed` usage)        | Token usage, sessions, cost, model breakdown  |
| **Muse**           | SQLite session index                               | Prompt activity, sessions, model breakdown    |
| **Claude**         | JSONL session transcripts                          | Token usage, sessions, model breakdown        |
| **Droid**          | JSONL session transcripts                          | Message activity, sessions                    |
| **DeepSeek (DSH)** | JSON session cache (`~/.dsh/storages`)             | Token usage, sessions, model breakdown        |
| **Nous Hermes**    | SQLite DB (`~/.hermes/state.db`)                   | Token usage, sessions, cost, model breakdown  |
| **Zed**            | SQLite DB (`~/.local/share/zed/threads/threads.db`)| Token usage, sessions, model breakdown        |
| **command-code**   | JSONL transcripts                                  | Message activity, sessions, model breakdown   |
| **Agy**            | Transcript logs (JSONL)                            | Step activity, sessions, model breakdown      |

Tools with token data appear in the **Token Warriors** leaderboard; activity-only tools appear in **Activity Hunters**.

Each tool also accepts short aliases: `mimo`, `oc`, `cmd`, `whale`, `zc`, `ccode`, `dsh`, `deepseek`, `hermes`, `nous`.

## Install

### Quick Install

```bash
# Automated installer (Linux & macOS)
curl -fsSL https://jadmadi.net/thermal/install.sh | sh

# Homebrew (macOS & Linux)
brew install jadmadi/tap/thermal

# Go toolchain
go install github.com/jadmadi/thermal/cmd/thermal@latest
```

Prefer a hosted page? The documentation site in
[`docs/pages`](docs/pages) covers the same ground with rendered terminal
output: https://jadmadi.net/project/thermal/

Or download a pre-built binary from [Releases](https://github.com/jadmadi/thermal/releases).

All official releases provide cryptographic build provenance conforming to **SLSA Build Level 3** (`checksums.txt.intoto.jsonl`) generated via OpenSSF. You can independently verify the provenance and integrity of any release asset using [`slsa-verifier`](https://github.com/slsa-framework/slsa-verifier):

```bash
# Verify checksums.txt against SLSA Level 3 provenance
slsa-verifier verify-artifact checksums.txt \
  --provenance-path checksums.txt.intoto.jsonl \
  --source-uri github.com/jadmadi/thermal \
  --source-tag v0.20.0

# Verify the downloaded archive against the verified checksums
sha256sum --check --ignore-missing checksums.txt
```

Or build from source using the included build script:

```bash
git clone https://github.com/jadmadi/thermal
cd thermal
./build.sh --release   # Builds stripped production binary (~10.7MB) with embedded version tags
```

You can run `./build.sh --help` to explore available build modes (`--release`, `--dev`, `--upx`) and cross-compilation targets. Or build manually with Go:

```bash
CGO_ENABLED=0 go build -ldflags="-s -w" -trimpath -o thermal ./cmd/thermal
```

## Update

If you installed via binary or `go install`:

```bash
thermal upgrade
```

This checks GitHub for a newer release, downloads the matching binary for your OS/arch, and atomically replaces the running binary. Upgrading across minor versions? Consult **[docs/MIGRATION.md](docs/MIGRATION.md)** for breaking changes, retired aliases, and JSON schema updates.

Thermal also checks for newer releases in the background once a day (cached in `~/.cache/thermal/update.json`) and prints an update reminder to stderr during interactive terminal sessions when a new release is available. You can opt out at any time with `--no-update-check` or by setting `THERMAL_NO_UPDATE_CHECK=1`.

If you installed via `go install`, you can also update with:

```bash
go install github.com/jadmadi/thermal/cmd/thermal@latest
```

Check your current version:

```bash
thermal version
```

## Usage

```bash
# Default: leaderboard showing all installed tools
thermal

# Show a specific tool's heatmap
thermal --tool opencode
thermal --tool codex
thermal --tool devin

# Auto-detect the first installed tool
thermal --tool auto

# Override the data path for a tool
thermal --tool opencode --db /path/to/opencode.db

# Show last 26 weeks (default: 52, range: 4-104)
thermal --weeks 26

# Output raw JSON
thermal --json

# Enable verbose diagnostic warnings (outputs non-fatal loading errors to stderr)
thermal --verbose

# Disable colors
thermal --no-color
```

The leaderboard ranks by contribution streak. To rank by volume instead:

```bash
thermal --sort tokens   # biggest token consumers first
thermal --sort cost     # biggest recorded spend first
```

## Reports

Daily, weekly, and monthly reports fold the same data into period tables with tokens, cost, and per-model rows:

```bash
# Last 7 days for OpenCode
thermal opencode daily --last 7

# Weekly report for every installed tool
thermal weekly

# A date window (YYYY-MM-DD or YYYYMMDD)
thermal weekly --since 2026-08-01 --until 2026-08-31

# This month, with a row per model
thermal monthly --last 1 --breakdown

# Oldest first, weeks starting on Monday
thermal weekly --order asc --start-of-week monday

# JSON for scripting
thermal weekly --json
```

![Thermal weekly report](docs/pages/shot-weekly.webp)

Daily, weekly, and monthly tables list token-bearing periods only: days with
no classified tokens, no recorded cost, and no model attribution (pure step
or message counts, empty sessions) are skipped so the Tokens column and the
Total row stay in tokens. That activity still counts toward streaks and the
leaderboard.

## Charts

Every report takes `--chart` to print bar rows under the table. The bars are
plain text, so they survive being pasted into a chat, an issue, or a commit
message, where a terminal heatmap does not.

```bash
thermal projects --chart          # bars under the project table
thermal models --chart            # bars plus estimated cost per model
thermal weekly --chart            # one bar per week
thermal weekly --chart --sort cost
```

Each bar prints its number beside it, so nothing depends on colour, and the
caption names the scale. A chart draws its first twelve rows and says how many
it left out, because a bar chart with eighty rows is a second copy of the table
rather than a chart. `--chart` never changes `--json` output.

## The dashboard

`thermal dashboard` opens the same numbers as an interactive screen: Overview,
Projects, Mix, Models and Stats, aggregated from one load of the data.

```bash
thermal dashboard
```

| Key | Does |
|---------|------------------------------------------|
| `q` | quit |
| `1`-`5` | jump to a view |
| `tab` | next view |
| `j` / `k` | move down and up |
| `g` / `G` | first and last row |
| `s` | cycle sort |
| `t` | toggle tokens and cost |
| `r` | cycle range: 30d, 90d, 1y, all |
| `f` | cycle the tool filter (Projects) |
| `v` | mix by tool or model (Mix) |
| `l` | histogram scale (Stats) |
| `enter` | open a project detail |
| `esc` | back |
| `?` | help |

Every view total equals the matching report command for the same window, and a
test asserts that rather than leaving it to inspection. A piped stdout is told
to use the static commands instead, and `--json` never opens a terminal UI.

Cost is estimated for the tools that record none, and the estimated share is
labelled wherever it appears. Day granularity limits switching analysis: a
change that happens twice in one day shows as one switch.

## Projects

Group tokens, cost, and activity by project. thermal walks each recorded directory up to its nearest git repository, so subdirectories and worktrees fold into one project, and the same project is merged across every tool that touched it.

```bash
# Rank every project by tokens
thermal projects

# One tool only
thermal opencode projects

# A window
thermal projects --last 30
thermal projects --since 2026-08-01 --until 2026-08-31

# Rank by something else: cost, days active, or most recent activity
thermal projects --sort cost
thermal projects --sort recent
thermal projects --sort days --order asc

# Tool split and top models under each project
thermal projects --breakdown --top 5

# Limit the printed rows, 0 means all
thermal projects --top 10

# JSON carries every project and the full path
thermal projects --json
```

![Thermal projects report](docs/pages/shot-projects.webp)

```
  Thermal · projects

  #    Project                       Tools                    Tokens       Cost  Days  Last
  ───────────────────────────────────────────────────────────────────────────────────────────────
   1.  atlas-gateway (core)          OpenCode,Devin +4          5.1B    $216.85    14  2026-09-16
        tools   OpenCode 2.9B · Devin 2.0B · Codex 250.3M · +3
        models  deepseek-v4.1-flash 1.4B · muse-spark-1.3-contributor-free 820.4M · +7
   2.  beacon-api                    Devin,MiMoCode +2          3.8B      $4.10    10  2026-08-12
   3.  solaris-engine (infra)        Codex,Devin,OpenCode     688.8M      $0.07     7  2026-09-07
```

The Project column shows the repository directory name. When two projects share one, the distinguishing parent appears in parentheses, like `atlas-gateway (core)`. Tools rank by the tokens they contributed, and the breakdown lines show tokens rather than shares because some tools record no model attribution.

Project attribution uses the token tools: OpenCode, MiMoCode, ZCode, Codex, Devin, Claude, Grok, codewhale, DeepSeek (DSH), and Nous Hermes. Agy records no project.

## Models

Rank models by token volume across every tool, with the tools that used each one.

```bash
# Global ranking
thermal models

# One tool only
thermal opencode models

# A window, or ranking by estimated cost
thermal models --last 30
thermal models --sort cost

# Limit rows, or export
thermal models --top 10
thermal models --json
```

```
  Thermal · models

  #    Model                           Tools                    Tokens       Cost  Days  Last
  ─────────────────────────────────────────────────────────────────────────────────────────────────
   1.  deepseek-v4.1-flash             OpenCode,ZCode             3.9B     $23.29     8  2026-09-17
   2.  deepseek-v4-flash-0731          MiMoCode,OpenCode +1       1.1B     $26.62     9  2026-09-12
   3.  gpt-5.6-sol                     Codex                    386.8M    $256.25    10  2026-09-11
```

Cost in this view is always an estimate from models.dev list prices, because recorded cost belongs to a session or a day, never to one model. Model names are compared case insensitively, so `GLM-5.3-Flash` from ZCode and `glm-5.3-flash` from OpenCode count as one model.

## Analytics: mix, stats, trend

Beyond tabular period reports, Thermal provides three analytical lenses into agent usage:

### `thermal stats`
High-density 9-box FinOps grid and activity taxonomy by default. Interactive TUI with live period switching (`[`/`]`, `1`..`6`, `Today`, `7D`, `30D`, `Month`, `6M`, `Lifetime`) and project filtering (`p`). For the classical volume distribution histogram and percentiles, pass `--distribution` (or `--dist`):

```bash
thermal stats                          # interactive 9-box FinOps grid (default)
thermal stats --distribution           # daily volume distribution histogram
thermal stats --dist --metric cost     # daily spend distribution
thermal opencode stats                 # single tool stats
```

```
  Thermal · stats · tokens

  Active days  67
  Total        32.8B
  Mean         489.2M
  Median       306.6M
  p90          1.2B
  Max          2.2B

  Weekday profile
  Sunday          462.5M  ██████████······   10 days
  Monday          451.6M  ██████████······   11 days
  Tuesday         342.8M  ████████········    8 days
  Wednesday       618.9M  ██████████████··   10 days
  Thursday        674.8M  ████████████████   10 days
  Friday          477.2M  ███████████·····    9 days
  Saturday        356.5M  ████████········    9 days

  Token composition
  Cache read           31.3B  ████████████████   95.6%
  Cache write          23.5M  █···············    0.1%
  Uncached input        1.3B  █···············    4.0%
  Output               83.9M  █···············    0.3%
  Reasoning            13.2M  █···············    0.0%
  Cache hit rate: 95.9% of prompt tokens read from cache

  Distribution
       0 — 224.5M  ████████████████████████    28
  224.5M — 449.1M  █████████···············    11
  449.1M — 673.6M  ██████··················     8
  673.6M — 898.2M  ████████················    10
    898.2M — 1.1B  █·······················     2
      1.1B — 1.3B  █·······················     2
      1.3B — 1.6B  █·······················     2
      1.6B — 1.8B  ························     0
      1.8B — 2.0B  ██······················     3
      2.0B — 2.2B  █·······················     1

  Top days
  2026-08-31         2.2B (outlier)
  2026-09-17         2.0B (outlier)
  2026-08-07         1.9B (outlier)
  2026-09-16         1.8B (outlier)
  2026-09-12         1.5B (outlier)

  Outliers above 888.7M (median + 2 MAD): all 5 top days above, plus 5 more
```

### `thermal mix`
Tool or model market-share evolution over time, dominant tool identification, tool switching frequency, and Shannon entropy spread:

```bash
thermal mix                       # tool mix by week
thermal mix --grain month         # monthly mix
thermal mix --by model            # model mix
thermal mix --metric cost         # spend share mix
```

```
  Thermal · mix · by tool · tokens

  Period        Devin         OpenCode      MiMoCode      Codex         other (4)          Total
  ──────────────────────────────────────────────────────────────────────────────────────────────
  2026-07       99%           0%            0%            0%            0%                  1.8B
  2026-08       85%           4%            7%            4%            0%                 16.3B
  2026-09       24%           68%           0%            2%            6%                 14.6B
  ──────────────────────────────────────────────────────────────────────────────────────────────
  Total         59%           32%           4%            3%            3%                 32.8B

  Dominant   Devin
  Switches   24 (2 in 2026-06, 3 in 2026-07, 9 in 2026-08, 10 in 2026-09)
  Spread     0.45 (1 = one tool, 0 = even spread)
```

### `thermal trend`
Ordinary least squares linear regression over daily activity with projection and confidence band to the next period end:

```bash
thermal trend
thermal trend --metric cost
thermal devin trend
```

```
  Thermal · trend · tokens

  Range        2025-09-26 to 2026-09-21
  Days         361
  Mean         90.8M
  Slope        +1.3M per day
  Direction    rising

  Projection to 2026-09-30 (9 days)
  Expected     336.3M
  Band         0 to 855.4M
```

### `thermal replay`
Simulate your real local developer workload against alternative subscriptions ($20/mo Claude Pro, $200/mo Claude Max, Cursor Pro) and API price cards (DeepSeek V3, Claude 3.5/3.7 Sonnet, GPT-4o) with dynamic rate-limit throttling analysis and cache efficiency accounting:

```bash
# Compare default commercial subscription plans and pay-as-you-go API tiers
thermal replay

# Replay workload specifically against a candidate model rate card
thermal replay --against deepseek-v3
thermal replay --against claude-3-7-sonnet --since 2026-08-01

# Compare custom plans or all available standard plans side-by-side
thermal replay --compare all
thermal replay --compare "claude-pro,claude-max,cursor-pro,deepseek-api"

# JSON output for financial modeling
thermal replay --json
```

```
  Thermal · replay · 30-day workload simulation

  Real Workload
  Active days: 28 ·  Total: 18.9B  · Cache hit rate: 97.6%  · Spend/mo: ~$5897.68
  Daily volume: Median 537.8M  · p90 burst 1.8B  · Peak 2.2B

  Plan / Target Model         Type         Cost/Mo     Delta vs Actual  Capacity Verdict                
  ──────────────────────────────────────────────────────────────────────────────────────────────────────
  Claude Pro ($20)            Sub           $20.00   -$5877.68 (-100%)  FAIL (throttled 28/28 days (100%))
  Claude Team/Max ($200)      Sub          $200.00    -$5697.68 (-97%)  FAIL (throttled 26/28 days (93%))
  Cursor Pro ($20)            Sub           $20.00   -$5877.68 (-100%)  FAIL (throttled 27/28 days (96%))
  ★ DeepSeek V3 (API)         Payg         $983.31    -$4914.37 (-83%)  PASS (0% throttled (unmetered API))
  Claude 3.5 Sonnet (API)     Payg        $7541.10    +$1643.42 (+28%)  PASS (0% throttled (unmetered API))
  ──────────────────────────────────────────────────────────────────────────────────────────────────────

  Recommendation:
  • Your median daily volume (537.8M) and p90 burst (1.8B) exceed flat $20/mo rate limits on heavy days.
  • Switching to DeepSeek V3 (API) would cost ~$983.31/mo with 0% throttling, saving $4914.37/mo.
```

### FinOps 9-Box Grid & Activity Taxonomy (`thermal stats`)
High-density 9-box FinOps grid view and activity taxonomy decomposition. Categorizes workload into Coding, Debugging, Testing, and Exploration, while tracking prompt cache efficiency, financial savings, and MCP tool overhead. Features live reactive period switching (`Today`, `7 Days`, `30 Days`, `This Month`, `6 Months`, `Lifetime`) and project filtering (`[p]`):

```bash
# Interactive responsive 9-box Bubble Tea TUI with live period switching
thermal stats

Frequently Asked Questions