thermal AGENTS.md

AGENTS.md — Thermal Coding Standards & Architecture Guide

This document defines the architectural conventions, coding standards, loader requirements, build quirks, and historical lessons for Thermal (github.com/jadmadi/thermal). Any AI coding assistant (Claude Code, Gemini CLI, Devin, OpenCode, Cursor, etc.) working on this repository MUST read and adhere to these standards.

---

1. Project Purpose & Architecture

Thermal (thermal) is a high-performance, zero-allocation terminal contribution heatmap and leaderboard tool for AI coding assistants. It scans local databases and session transcripts across multiple AI tools, calculates activity and token metrics, and renders beautiful terminal heatmaps.

Directory Structure

thermal/
├── cmd/thermal/         # Main CLI entrypoint (main.go, upgrade.go for self-update mechanism)
├── internal/loaders/    # Tool-specific ingestion engines and incremental delta-cache
├── internal/thermal/    # Heatmap algorithms, streak calculation, and time parsing
├── internal/render/     # Terminal formatting, color palettes, dashboard & leaderboard UI
├── internal/version/    # SemVer constants and ldflag injection targets
├── build.sh             # Local multi-target build and UPX compression script
└── .goreleaser.yml      # Automated GitHub Actions release configuration

---

2. Core Coding & Architectural Standards

A. Read-Only Data Ingestion (internal/loaders/)

1. Never Modify User Data: All SQLite connections MUST open in strictly read-only mode using URI parameters:

   db, err := sql.Open("sqlite", "file:"+dbPath+"?mode=ro")
   

2. Memory-Mapped I/O: Immediately after opening any SQLite database, execute PRAGMA mmap_size to enable memory mapping for instant scanning of multi-gigabyte files:

   db.Exec("PRAGMA mmap_size=268435456") // 256MB mmap window
   

3. Robust Time Parsing (parseSessionTime): AI tool timestamps vary wildly across tools and versions (RFC3339 strings, Unix seconds, milliseconds, microseconds, SQLite strings). Always use robust multi-format parsing or time_test.go utilities. Never assume a single fixed format.
4. Incremental Delta Caching (cache.go): For large databases (Devin, OpenCode, MiMoCode, Codex) and multi-file scanners (command-code, Agy), use the LoadOrScanWithCache mechanism (~/.cache/thermal/<tool>.json). Store exact file modification times (mod_time), sizes (size), or max seen transaction IDs so subsequent invocations take under 10ms.
5. Concurrency Safety: Multi-file, directory, and JSONL log scanners (command-code, Codex rollout logs, Agy overview logs) must use bounded worker pools (sync.WaitGroup or semaphore channels capped at ~16 workers) with thread-safe aggregation (sync.Mutex). Never spawn unbounded goroutines over thousands of files.