Token Doctor

Token Doctor

Platforms: Claude Code / Cowork and Codex. scripts/inventory.py detects the host (via the platform stamp install.sh writes, or AI_FIRST_PLATFORM) and routes: Claude Code (~/.claude/projects) + Cowork transcripts, or Codex rollouts (~/.codex/sessions). Codex token usage comes from Codex's own per-response token_count events; cost uses OpenAI list rates in pricing.py (gpt-5.4 family; unknown models show token counts with no fabricated cost). Antigravity is unsupported: its IDE store is AEAD-encrypted at rest and its CLI store has no parseable turn/token content, so the skill prints a clear "not available" message and exits.

Two-stage diagnostic. Stage 1 is fast and lands directly in the terminal so the user always walks away with their numbers. Stage 2 is opt-in, fans out subagents over hotspots, and writes a tight Markdown report.

Read this whole file before running.

When to run

Trigger phrases: "diagnose my Claude habits", "why am I spending so much", "where are my tokens going", "audit my spend", "token doctor", "what's driving my Claude bill".

Do NOT trigger for:

• "what tasks do I do with Claude" → that's task-profile.
• "where did I work on X" → that's session-search.

The line is: token-doctor is about cost shape, not task inventory or recall.

Prerequisites

• Claude Code transcripts: ~/.claude/projects/*/*.jsonl (CLI and desktop app)
• Sub-agent transcripts: ~/.claude/projects/*/<sid>/subagents/**/*.jsonl, including workflow agents under subagents/workflows/<wf>/
• Claude Cowork transcripts (optional): ~/Library/Application Support/Claude/local-agent-mode-sessions/*/*/local_*/audit.jsonl
• Python 3, stdlib only. No external services.

If neither path exists, stop and say so.

What counts as one session

Sub-agent transcripts are separate files but the same piece of work, so their cost rolls into the parent session rather than appearing as sessions of their own. This matters when you read the report:

• cost_usd is main conversation plus fan-out. main_cost_usd and subagent_cost_usd split it.
• Turn counts, the timeline, cache rebuilds and the re-read ratio are main-session figures. They describe how that one conversation's context grew; sub-agents have their own context.
• So a session can show 100 turns and $641. That is not a contradiction, it is fan-out. Say so rather than letting the reader trip over it.
• One turn = one assistant message, not one transcript line. Claude Code writes a line per content block (thinking, text, each tool_use) and repeats the same usage object on every one, so counting lines inflates turns and cost by roughly 2-3x. The inventory dedupes by message.id. Turn counts from an older run of this skill are not comparable with these.

Automation excluded by default: sdk-cli background dispatch, paperclip, ditto-routines, scheduled tasks, and the automation slash commands. Desktop-app sessions are interactive work and are counted.

STAGE 1 — Fast diagnosis (always runs, you write the report)

The goal is: the user invokes the skill, sees a clean doctor's report within 10 seconds, knows which projects are healthy and which are bleeding, and can decide whether to go deeper. You write the report directly in your message based on the JSON the scripts produce. The scripts compute, you communicate.

Step 1.1 — Inventory (deterministic)

~/.claude/skills/token-doctor/scripts/inventory.py --since YYYY-MM-DD --out out/sessions.jsonl

Default window: last 90 days. Flags: --since, --until, --all, --include-automation, --no-cowork. Automation runs (sdk-cli background dispatch, paperclip, /loop, /schedule, ditto-routines, scheduled-tasks) excluded by default.

--until YYYY-MM-DD means midnight at the start of that day, so it excludes that day's sessions. To include today, leave --until off.

The scan prints how many sub-agent transcripts it rolled into parent sessions. If it also reports sub-agents with no parent session on disk, that cost is not in the totals; mention it only if it is material.

Step 1.2 — Aggregate (deterministic)

~/.claude/skills/token-doctor/scripts/personal_stats.py --in out/sessions.jsonl --out out/user-stats.json

Prints a single confirmation line. The full data is in out/user-stats.json.

Step 1.3 — Read the JSON and write the doctor's report

Read out/user-stats.json. Then write the report directly in your message as terminal-style ASCII with emojis. The user reads your message; no intermediate file.

Report structure (mandatory sections, in order)

🩺 ┌────────────────────────────────────────────────────────────────────┐
   │            TOKEN DOCTOR · personal diagnosis                       │
   └────────────────────────────────────────────────────────────────────┘

  Patient: <user's first name or "you">
  Window:  <window dates from inventory>
  Spend:   $<total> list-price equivalent · <conv count> conversations

  ── Vital signs ─────────────────────────────────────────────────────────

  🔴/🟡/🟢 Marathon (≥300 turns)    <N> conv  ·  $<X>  ·  <Y>% of spend
  🔴/🟡/🟢 Fan-out (≥5 sub-agents)  <N> conv  ·  $<X>  ·  <Y>% of spend
  🔴/🟡/🟢 Zombie (≥4h wall clock)  <N> conv  ·  $<X>  ·  <Y>% of spend
  🔴/🟡/🟢 Cache rebuilds            <N> events · <Z>M tokens · ~$<X>
  🔴/🟡/🟢 Re-read ratio             <X>×   (healthy ≤15×, org avg 30×)
  📈 Peak context observed       <X>k tokens
  🌳 Sub-agent cost               $<X> of $<total>  (<Y>%) across <N> transcripts

  ── Spend by conversation length ────────────────────────────────────────

       1 to 5        <bar>   <%>   (<N> conv)
       6 to 20       <bar>   <%>   (<N> conv)
       …
       1,000+        <bar>   <%>   (<N> conv)

  ── Model mix ───────────────────────────────────────────────────────────

    <model>        $<X>   <%>   <N> turns    main $<X>/<N>t · sub $<X>/<N>t
    <model>        $<X>   <%>   <N> turns    main $<X>/<N>t · sub $<X>/<N>t
    …

  ── Diagnosis ───────────────────────────────────────────────────────────

  <2-4 sentences synthesizing the vitals into one clear picture. Lead with
  the dominant antipattern in this user's data, then the corollary cost. End
  with one line about the strongest positive signal you see.>

  ── Project chart ───────────────────────────────────────────────────────

  ✅ clean · 🏃 marathon · 🌳 fanout · 🔄 rebuilds · 🧟 zombie · ⚠️ multiple

  <emoji>  $<X>  <truncated cwd>                              <meta line>
  <emoji>  $<X>  <truncated cwd>                              <meta line>
  … up to 10-12 rows from by_cwd_top

  ── Treatment plan ──────────────────────────────────────────────────────

  💚 Keep doing:
     <bullet referencing a clean project from by_cwd_top or by_cwd_clean_deeper,
      OR a positive structural signal like a high short_share if no clean cwd is in top 12>
     <2-3 bullets total>

  🎯 Change first:
     <one concrete action tied to the biggest lever, with cited project>
     <2-3 bullets total, ordered by expected impact>

  ── Want a deeper look? ─────────────────────────────────────────────────

  <one-line question asking if they want the deep dive>

Rules when writing the report

• Use the emojis above consistently. Box-drawing characters (─ ┌ └ │) are fine and make the report look like a medical printout.
• Traffic-light dots: 🔴 = bad, 🟡 = watch, 🟢 = healthy. Apply the bands in the rubric below.
• Per-project emoji must come from by_cwd_top[i].emoji in the JSON. Do not re-classify.
• Model mix comes from model_mix, already sorted by cost. Show every model down to 1% of spend, then stop. Use readable names (claude-opus-5 → Opus 5, claude-fable-5-1 → Fable 5.1). The main / sub split is the point of the section: a model that is cheap in the main conversation and expensive across sub-agents is the clearest lever in the whole report, because sub-agent model tier is a one-line change in an Agent(...) call. Call that out when you see it.
• Fan-out uses fanout_conv / fanout_cost / fanout_share (sessions with ≥ 5 sub-agents) and subagent_cost / subagent_share (fan-out's share of total spend). If subagent_files is 0, drop both the fan-out vital and the sub-agent line rather than printing zeroes.
• Bars for the length distribution: build them with █ characters proportional to the share. Use a fixed width like 36 chars.
• The diagnosis paragraph is yours to write — it is the doctor's read on the data. Be specific. Don't restate the numbers; conclude from them. Aim for 3-5 sentences max. Examples of good diagnostic sentences:
  • "Your spend is concentrated in a small number of very long sessions: 22 conversations carry 70% of your bill."
  • "Cache rebuilds are minor at $388, but the re-read ratio of 23× tells me your context grows fast inside those long sessions."
  • "Three of your top five projects are evaluation runs from last month. Each is one long session; splitting them would compound."
• Treatment plan must include both "keep doing" AND "change first" sections. Skipping the positive section is forbidden. Pick from:
  • by_cwd_top entries with emoji == "✅" for clean
  • by_cwd_clean_deeper for clean projects below the top 12
  • short_share if neither is available — frame as "X% of your spend is in short focused sessions, so the habit is there, you just don't use it everywhere"
• Cite specific projects. Truncate cwds to the last 36-44 chars with a leading … if they're long. Drop the /Users/<name>/ prefix when it makes the line cleaner.
• No em-dashes. Use commas, semicolons, or periods.
• No "waste", "burning", "bad habit". Use "cost", "spend", "context", "rebuild".