tracegauge

tracegauge reads your Claude Code session transcripts on your own machine and shows where the tokens and dollars went, which retries were pure waste, and which cache re-writes cost you money.

Install and try it

pip install tracegauge
tracegauge quickstart   # scores a bundled synthetic session: no network, no files of yours read
tracegauge score        # scores your most recent Claude Code session

What it finds

Real output of this version on data in the repository. Lines are selected from the report, never edited. scripts/gen_readme_demo.py regenerates both blocks and the recording above, and tests/test_readme_demo.py fails when this README or the recording drifts from what the command prints.

tracegauge quickstart on the bundled sample, a synthetic session shipped in the package. It gets a token verdict against the research-recon band, one deterministic waste finding with its proof turns, and the cost split by where the money went:

tracegauge quickstart -- no local judge, no network call, no files of yours read.
── TOKEN ECONOMY ───────────────────────────────────────────────────────────
  Real tokens: 531,840
  Verdict:     within_band
  Baseline:    research-recon — p25: 411,052 / median: 620,842 / p75: 1,194,136
── TRAJECTORY QUALITY ──────────────────────────────────────────────────────
  Verdict:     UNAVAILABLE (no local judge configured)
── DETERMINISTIC WASTE ─────────────────────────────────────────────────────
  Events:  1 event(s)
  [1] REPEATED-FAILED-RETRY — 2 retries, turns: 61→62, 64→65  ~$0.041
── COST BREAKDOWN ──────────────────────────────────────────────────────────
  Context re-send (cache reads)                       $1.89   51.3%
  Context growth (cache writes)                       $0.33    8.8%
  Output                                              $0.80   21.8%
  Fresh input                                         $0.63   17.0%
  Detected waste (redundant reads, retry loops)       $0.04    1.1%
  Total (priced)                                      $3.69

The cache-churn detector, on a second synthetic session with three planted cache re-writes (an idle gap past the cache lifetime, a model switch and a compaction; seeded generator, tests/churn_synth.py). It reports what each re-write cost above reading the cache back, and says the cause is a rule on transcript markers and timestamps, not a verified fact. Method and limits: docs/CACHE_CHURN.md.

── CACHE CHURN ─────────────────────────────────────────────────────────────
  3 event(s) where cached context was re-written instead of read: $0.38
  above what reading it would have cost. Main chain $0.38 (3), subagents
  $0.00 (0).
    TTL gap (idle past the cache lifetime)      1       $0.06
    model switch                                1       $0.16
    compaction                                  1       $0.17
  Plausibly avoidable (a judgement): $0.21; not avoidable by a setting (idle
  over an hour, compaction): $0.17.
    [main] turn 29→30: compaction, gap 78s vs 300s TTL, 35,615 tokens re-
    written, $0.17
    [main] turn 19→20: model switch, gap 53s vs 300s TTL, 32,860 tokens re-
    written, $0.16
    [main] turn 9→10: ttl gap, gap 2,632s vs 300s TTL, 23,145 tokens re-
    written, $0.06
  Cause = a rule on transcript markers and timestamps, not a verified fact.

Every figure in this block is rounded independently, and totals use the unrounded values. So the three cause rows add to $0.39 while the $0.38 total is the sum of the unrounded amounts, and the $0.21 "plausibly avoidable" figure sits beside model-switch and TTL-gap rows ($0.16 + $0.06) that add to $0.22.

Commands

tgauge is a short alias for tracegauge. The old tes command still works until 0.18 (migration guide). Full usage and the SDK: docs/COMMANDS.md.

Supported agents

Claude Code is supported. Other agents are planned; none is supported today. Each needs its own transcript adapter and a fresh validation run, not a flag.

Methodology

Three readings, never blended into one score. Token economy compares a session's tokens (each API response counted once, cache re-reads excluded) with the p25 to p75 band for the same task type. The bundled bands come from 71 Claude Code sessions of one developer, not filtered for quality, so "above the band" means heavier than that developer's typical session, not wasteful, and not heavier than other developers. Trajectory quality is an optional LLM judge: it is UNAVAILABLE without one, it was checked against a reference model and not against human labels, and its negative verdicts are model-dependent. The waste detectors catch two observable patterns only (identical failed retries and re-reads of unchanged files) and miss judgment-of-progress waste by design. Cache churn is a separate section of the score output, not a third waste detector: it finds turns where a cached prefix that the previous turn had read was written again, and prices each re-write above what reading it back would have cost; its cause label is a rule over transcript markers and timestamps, not a measurement of the vendor's cache, and the transcript cannot settle the cause (docs/CACHE_CHURN.md). Costs are API-equivalent rates from a bundled, dated price table, and a model missing from it is shown as unpriced, never as $0. Scoring makes no external network call (the optional local Ollama endpoint aside); the only data that can leave your machine is an opt-in API judge you consent to per session. Figures whose source data is not in this repository are labelled as the maintainer's unpublished local measurement. Everything, with every caveat and where each number comes from: docs/METHODOLOGY.md. Privacy: PRIVACY.md.

Apache-2.0 from 0.16.0 onward. Releases 0.15.0 and earlier on PyPI were published under AGPL-3.0-only and remain under that license for anyone who received them; the change applies to 0.16.0 and later only. Third-party fonts bundled in the package keep their own SIL OFL 1.1 license, and third-party datasets in the repository keep theirs; see NOTICE and DATA_SOURCES.md.