Episode 11: HUD Data Sources Deep Dive

Key Takeaway: Understanding where HUD's data comes from enables precise troubleshooting.

---

11.1 Three Data Sources

Source	Location	Update Frequency	Content
stdin JSON	Piped in by Claude Code	~300ms	Model, context, token details, cost, usage
Transcript JSONL	~/.claude/projects/<path>/<session-id>.jsonl	Real-time	Tool calls, agent activity, todo list, cumulative tokens
Context Cache	~/.claude/plugins/claude-hud/context-cache/<hash>.json	Written by HUD (3s TTL)	stdin snapshot, used as fallback

---

11.2 stdin JSON Structure

Claude Code calls the statusLine command every ~300ms, passing JSON via stdin:

{
  "transcript_path": "~/.claude/projects/.../session-id.jsonl",
  "cwd": "/Users/eric/work/teachagent",
  "model": { "id": "claude-opus-4-7", "display_name": "Opus 4.7" },
  "context_window": {
    "context_window_size": 200000,
    "total_input_tokens": 67000,
    "used_percentage": 33,
    "current_usage": {
      "input_tokens": 318,
      "output_tokens": 59,
      "cache_creation_input_tokens": 0,
      "cache_read_input_tokens": 66368
    }
  },
  "cost": { "total_cost_usd": 0.42 },
  "rate_limits": {
    "five_hour": { "used_percentage": 25, "resets_at": 1777532000000 },
    "seven_day": { "used_percentage": 60 }
  }
}

---

11.3 stdin Fields to HUD Rendering

stdin Field	HUD Rendering
model.display_name	[Opus 4.7]
context_window.used_percentage	Context bar percentage
context_window.current_usage	(in: 318, cache: 66k)
cost.total_cost_usd	$0.42
rate_limits.five_hour	Usage bar

---

11.4 Transcript Cache Structure

HUD parses transcript JSONL and caches:

{
  "version": 3,
  "data": {
    "tools": [{ "name": "Read", "target": "package.json", "status": "completed" }],
    "agents": [{ "type": "Explore", "description": "Research...", "status": "completed" }],
    "todos": [{ "content": "Fix auth bug", "status": "in_progress" }],
    "sessionTokens": {
      "inputTokens": 218486,
      "outputTokens": 4832,
      "cacheReadTokens": 1047488
    }
  }
}

---

11.5 sessionTokens vs current_usage

	sessionTokens (transcript)	current_usage (stdin)
Scope	Session cumulative across all turns	Single API request
Update timing	After each turn completes	Every statusLine refresh
Purpose	Session Tokens standalone line	Identity line token breakdown

---

11.6 Context Cache Fallback Mechanism

HUD persists stdin's context_window snapshot. When stdin occasionally drops data (e.g., Claude Code briefly flashes 0%), HUD recovers from cache.

Cache key = sha256(transcript_path), ensuring different sessions don't overwrite each other.

---

Next Episode: Episode 12 walks you through real debugging — the complete diagnostic flow when token details don't display.