What is Claude HUD?
Session Visibility at a Glance
Claude HUD gives you better insights into what's happening in your Claude Code session. It uses Claude Code's native statusline API — no separate window, no tmux required, works in any terminal.
Project
Always know which project you're working in with the current directory name displayed.
Context
Know exactly how full your context window is before it's too late with color-coded visual meter.
Tools
Watch Claude read, edit, and search files as it happens with real-time tool activity tracking.
Agents
See which subagents are running and what they're doing with live agent status.
Todos
Track task completion in real-time with progress counters and status updates.
Installation
Three Simple Steps
Add the Marketplace
Inside a Claude Code instance, add the plugin marketplace:
Install the Plugin
Install claude-hud from the marketplace:
Configure the Statusline
Run the setup command to configure the HUD:
The HUD appears immediately after setup — no restart needed. It updates every ~300ms with native token data from Claude Code, not estimates.
Understanding the Display
What Each Line Shows
| Element | Description | Example |
|---|---|---|
| Project | Current working directory folder name | 📁 my-project |
| Model | Current model in use | [Opus 4.5] |
| Context Bar | Visual meter with color coding (green → yellow → red) | ████░░░░░░ 19% |
| Config Counts | Number of CLAUDE.md files, rules, MCPs, and hooks loaded | 2 CLAUDE.md | 8 rules | 6 MCPs |
| Duration | How long the session has been running | ⏱️ 1m |
| Running Tools | Shows spinner with target file for active tools | ⟳ Read src/index.ts |
| Completed Tools | Aggregate by type with counts | ✓ TaskOutput ×2 |
| Agent Status | Agent type and what it's working on with elapsed time | ✓ Explore: Research patterns (5s) |
| Todo Progress | Current task or completion status with counter | ✓ All complete (5/5) |
How It Works
Under the Hood
Native Statusline API
Claude HUD uses Claude Code's native statusline API. No separate window, no tmux required, works in any terminal. The HUD is always visible below your input.
Real Token Data
Context usage comes directly from Claude Code — not estimated. The plugin parses the transcript for tool/agent activity and updates every ~300ms.
JSON Streaming
Claude Code sends stdin JSON to claude-hud, which processes it and outputs to stdout for display in your terminal. Clean, efficient, lightweight.
Transcript Parsing
The plugin reads the transcript JSONL file to track tools, agents, and todos. This gives you accurate, real-time information about your session.
Claude Code → stdin JSON → claude-hud → stdout → displayed in terminal ↘ transcript JSONL (tools, agents, todos)
Requirements
What You Need
Claude Code v1.0.80+
The statusline API was introduced in version 1.0.80. Make sure you're running a compatible version of Claude Code.
Node.js 18+ or Bun
The plugin is built with TypeScript and requires Node.js 18 or later. Bun is also supported as an alternative runtime.
# Clone the repository git clone https://github.com/jarrodwatts/claude-hud cd claude-hud # Install dependencies and build npm ci && npm run build # Run tests npm test
Install Claude HUD in three commands and gain instant visibility into context usage, tool activity, agent progress, and todo completion. Know what's happening, always.
Install Claude HUD →