mirror of
https://github.com/jarrodwatts/claude-hud.git
synced 2026-05-21 15:52:37 +00:00
bb77dd7cc3
Phase 1 of v2 upgrade: - Add PreToolUse hook for true "running" state before tool execution - Add UserPromptSubmit hook to track user prompts and idle state - Add Stop hook for idle detection when Claude finishes responding - Add PreCompact hook to track context compaction events - Enrich capture-event.sh with permission_mode, transcript_path, cwd - Add CostTracker for session cost estimation - Add SessionInfo type for tracking session state - Show idle indicator (💤/⚡) and permission mode in header - Show cost estimate when significant - Show compaction count warning - Show last user prompt preview 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Claude HUD
Real-time terminal dashboard for Claude Code. See context usage, tool activity, agent status, and more — all in a split pane next to your terminal.
Installation
claude /plugin install github.com/jarrodwatts/claude-hud
That's it. The HUD appears automatically when you start Claude Code.
Features
Context Health
The most important metric when working with AI. See at a glance:
- Token count with visual progress bar
- Burn rate — tokens consumed per minute
- Compaction warning when context is getting full
- Breakdown of input vs output token usage
Tool Activity Stream
Watch Claude work in real-time:
- Every tool call with status icons (✓ complete, ◐ running, ✗ error)
- Duration for each operation
- Smart path truncation showing filename + parent
- Color-coded: green for success, yellow for running, red for errors
Agent Tracking
When Claude spawns subagents:
- Type and description of each agent
- Live elapsed time counter
- Nested tool calls — see what the agent is doing
- Completion status
Session Statistics
- Total tool call counts by type
- Lines changed (+additions/-deletions)
- Session duration
- Number of completed agents
Additional Panels
- Todo List — Claude's current task tracking
- Modified Files — files changed this session
- MCP Status — connected MCP servers
Supported Terminals
| Terminal | Split Support |
|---|---|
| tmux | ✓ Native split pane |
| iTerm2 | ✓ Native split |
| Kitty | ✓ Remote control split |
| WezTerm | ✓ CLI split pane |
| Zellij | ✓ Native split |
| Windows Terminal | ✓ WSL split |
| macOS Terminal | Separate window |
| xterm (Linux) | Separate window |
| Others | Background process |
Keyboard Shortcuts
| Key | Action |
|---|---|
Ctrl+H |
Toggle HUD visibility |
Ctrl+C |
Exit HUD |
How It Works
Claude HUD uses Claude Code's plugin hooks to capture events:
- SessionStart — Spawns the HUD in a split pane
- PostToolUse — Captures every tool call
- SubagentStop — Tracks agent completion
- SessionEnd — Cleans up
Data flows through a named pipe (FIFO) to a React/Ink terminal UI.
Requirements
- Claude Code
- Node.js 18+ or Bun
jq(for JSON parsing in hooks)
Development
# Clone the repo
git clone https://github.com/jarrodwatts/claude-hud
cd claude-hud/tui
# Install dependencies
bun install
# Build
bun run build
# Run tests
bun test
# Start manually (for development)
bun run start -- --session test --fifo /tmp/test.fifo
License
MIT
Credits
Built with Claude Code and Ink.