Episode 12: Debugging — Token Details Not Showing

Key Takeaway: Real-world debugging experience — step-by-step guide to pinpoint why token details aren't appearing.

---

12.1 Symptom

HUD shows the context bar and percentage, but no (in: xxx, cache: xxx) breakdown.

---

12.2 Diagnostic Steps

Step 1: Check configuration

cat ~/.claude/plugins/claude-hud/config.json

Verify:

• showTokenBreakdown is not false (default: true)
• showSessionTokens is true

Step 2: Check contextCriticalThreshold

Token breakdown only shows when context >= contextCriticalThreshold. Default is 85%.

// Lower the threshold to show details earlier
{ "display": { "contextCriticalThreshold": 30 } }

Step 3: Verify data exists

ls -lt ~/.claude/plugins/claude-hud/context-cache/ | head -3
cat ~/.claude/plugins/claude-hud/context-cache/<latest-file>.json | python3 -m json.tool

If current_usage is null → Claude Code isn't providing this data (non-native Claude models may not support it).

Step 4: Check session tokens data

ls -lt ~/.claude/plugins/claude-hud/transcript-cache/ | head -3

If sessionTokens exists and total > 0, but HUD doesn't display → likely multi-line truncation.

Step 5: Rule out multi-line truncation

Expanded layout outputs multiple lines; session tokens line is last. Narrow terminals may truncate.

Fix: Disable unimportant elements:

{
  "display": {
    "showSessionName": false,
    "showClaudeCodeVersion": false,
    "showMemoryUsage": false,
    "showOutputStyle": false
  }
}

---

12.3 Diagnostic Decision Tree

Token details not showing
│
├─ Identity line missing (in/cache)?
│  ├─ contextCriticalThreshold too high (default 85%)
│  │  └─ Lower to 30
│  ├─ current_usage is null
│  │  └─ Non-native Claude model
│  └─ showTokenBreakdown = false
│     └─ Set to true
│
└─ Session tokens line missing?
   ├─ showSessionTokens = false → Set to true
   ├─ transcript cache has no sessionTokens → Session just started
   └─ Multi-line truncation → Disable unimportant elements or switch to compact

---

12.4 Non-Native Model Compatibility

Data	Native Claude	ZAI/Compatible Platforms
Context percentage	✅	✅
Token details	✅	⚠️ May be missing
Usage limits	✅	❌
Cost estimate	✅	⚠️ May be $0

HUD has context-cache fallback: even if stdin occasionally drops data, it recovers from the last complete snapshot.

---

Next Episode: Episode 13 covers Session and Session History — understanding the session lifecycle and data storage.