token-bleed-hunting
The authoritative method for hunting TOKEN BLEED — tokens an AI coding agent spends that buy no work — from OpenTelemetry metrics and events (Claude Code first-class) and local session transcripts, then fixing it forward in the repo's harness config so every future session is cheaper at the same capability. Encodes the loop — MINE telemetry for one repo against a rolling baseline, normalized per session and per unit of work → DIAGNOSE the bleed class (cache-busting / low cache-hit ratio, bloated always-loaded context, unbounded tool output, model-tier mismatch, retry and permission churn, compaction thrash, subagent overspawn, redundant re-reads, verbose output) → CONFIRM the cause in transcripts and tie it to a file → PROVE the fix keeps capability → FIX FORWARD via a PR that records the baseline and projected saving → VERIFY after merge that the saving landed → REPEAT. And the hard lines — cut waste, never work; harness config only, never application code; aggregate numbers only, never prompt or transcript content. Use whenever chasing agent token spend or cost, "where are our tokens going", "why did the Claude bill jump", a low cache-hit ratio, a high session start floor, CLAUDE.md or MCP bloat, huge tool results, querying claude_code.token.usage / cost.usage / api_request in any backend, checking whether a token-saving change worked, or running the token-bleed-hunter lane. Distinct from ci-speed-hunting (CI wall-clock time) and caveman (this session's output style).
Pinned to revision 6b9d66f636cc, so it is the text this page describes rather than whatever the author pushed since.
Files
- skills/token-bleed-hunting/SKILL.md
- skills/token-bleed-hunting/evals/triggering.json
- skills/token-bleed-hunting/references/claude-code-telemetry.md
- skills/token-bleed-hunting/references/queries.md
- skills/token-bleed-hunting/references/transcripts.md
- skills/token-bleed-hunting/scripts/telemetry-query.sh
- skills/token-bleed-hunting/scripts/transcript-stats.py
Every link opens the file at its source, pinned to the revision this page describes.