mirror of
https://github.com/jarrodwatts/claude-hud.git
synced 2026-05-18 05:32:44 +00:00
36b2a09210
- Add ARCHITECTURE.md, FAQ.md, LLM.md documentation - Add LICENSE (MIT), CODE_OF_CONDUCT.md, PR template - Add .editorconfig for consistent formatting - Add check.sh script for validation - Fix ESLint errors in hud-config.ts and settings-reader.ts - Various test and component improvements 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
60 lines
1.6 KiB
Markdown
60 lines
1.6 KiB
Markdown
# 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
|