claude-hud/docs/ARCHITECTURE.md

Architecture

Claude HUD is a Claude Code plugin that renders a real-time TUI from hook events.

High-Level Flow

Claude Code hooks
  -> scripts/capture-event.sh
  -> session FIFO (~/.claude/hud/events/<session>.fifo)
  -> tui/src/lib/event-reader.ts
  -> tui/src/hooks/useHudState.ts
  -> tui/src/app.tsx
  -> Ink UI panels

Plugin Structure

claude-hud/
  .claude-plugin/plugin.json
  hooks/hooks.json
  scripts/
  tui/

• .claude-plugin/plugin.json declares the plugin and hook entrypoints.
• hooks/hooks.json subscribes to Claude Code lifecycle events.
• scripts/ normalizes event payloads and launches the HUD.
• tui/ contains the Ink-based terminal UI.

Runtime Files

The HUD writes runtime artifacts under ~/.claude/hud/:

• events/<session_id>.fifo for the event stream
• pids/<session_id>.pid for the HUD process
• logs/<session_id>.log for fallback output

Key Components

• tui/src/lib/event-reader.ts reads the FIFO and reconnects if it drops.
• tui/src/hooks/useHudState.ts is the single source of truth for HUD state.
• tui/src/components/ renders panels such as ContextMeter, ToolStream, AgentList.
• tui/src/lib/unified-context-tracker.ts handles context usage and burn rate.
• tui/src/lib/cost-tracker.ts calculates input/output cost.

Hook Events

Common events used by the HUD:

• SessionStart: spawn HUD in a split pane
• PreToolUse: show tool in running state
• PostToolUse: record completion and metrics
• UserPromptSubmit: track prompts and idle state
• Stop: mark idle
• PreCompact: compaction counter
• SubagentStop: agent completion
• SessionEnd: cleanup