Claude HUD
A Claude Code plugin that shows what's happening — context usage, active tools, running agents, and todo progress. Always visible below your input.
🌐 English | 中文文档
Install
Inside a Claude Code instance, run the following commands:
Step 1: Add the marketplace
/plugin marketplace add jarrodwatts/claude-hud
Step 2: Install the plugin
⚠️ Linux users: Click here first
On Linux, /tmp is often a separate filesystem (tmpfs), which causes plugin installation to fail with:
EXDEV: cross-device link not permitted
Fix: Set TMPDIR before installing:
mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude
Then run the install command below in that session. This is a Claude Code platform limitation.
/plugin install claude-hud
After that, reload plugins:
/reload-plugins
Step 3: Configure the statusline
/claude-hud:setup
⚠️ Windows users: Click here if setup says no JavaScript runtime was found
On Windows, Node.js LTS is the supported runtime for Claude HUD setup. If setup says no JavaScript runtime was found, install Node.js for your shell first:
winget install OpenJS.NodeJS.LTS
Then restart your shell and run /claude-hud:setup again.
Done! Restart Claude Code to load the new statusLine config, then the HUD will appear.
On Windows, make that a full Claude Code restart after setup writes the new statusLine config.
What is Claude HUD?
Claude HUD gives you better insights into what's happening in your Claude Code session.
| What You See | Why It Matters |
|---|
| Project path | Know which project you're in (configurable 1-3 directory levels) |
| Context health | Know exactly how full your context window is before it's too late |
| Tool activity | Watch Claude read, edit, and search files as it happens |
| Agent tracking | See which subagents are running and what they're doing |
| Todo progress | Track task completion in real-time |
What You See
Default (2 lines)
[Opus] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)
- Line 1 — Model, provider label when positively identified (for example
Bedrock, Vertex), project path, git branch
- Line 2 — Context bar (green → yellow → red) and usage rate limits
Optional lines (enable via /claude-hud:configure)
◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2 ← Tools activity
◐ explore [haiku]: Finding auth code (2m 15s) ← Agent status
▸ Fix authentication bug (2/5) ← Todo progress
How It Works
Claude HUD uses Claude Code's native statusline API — no separate window, no tmux required, works in any terminal.
Claude Code → stdin JSON → claude-hud → stdout → displayed in your terminal
↘ transcript JSONL (tools, agents, todos)
Key features:
- Native token data from Claude Code (not estimated)
- Scales with Claude Code's reported context window size, including newer 1M-context sessions
- Parses the transcript for tool/agent activity
- Updates every ~300ms
Configuration
Customize your HUD anytime:
/claude-hud:configure
The guided flow handles layout, language, and common display toggles. Advanced overrides such as
custom colors and thresholds are preserved there, but you set them by editing the config file directly:
- First time setup: Choose a preset (Full/Essential/Minimal), pick a label language, then fine-tune individual elements
- Customize anytime: Toggle items on/off, adjust git display style, switch layouts, or change label language
- Preview before saving: See exactly how your HUD will look before committing changes
Presets
| Preset | What's Shown |
|---|
| Full | Everything enabled — tools, agents, todos, git, usage, duration |
| Essential | Activity lines + git status, minimal info clutter |
| Minimal | Core only — just model name and context bar |
After choosing a preset, you can turn individual elements on or off.
Manual Configuration
Edit ~/.claude/plugins/claude-hud/config.json directly for advanced settings such as colors.*,
pathLevels, maxWidth, threshold overrides, display.timeFormat, and display.promptCacheTtlSeconds. Running /claude-hud:configure
preserves those manual settings while still letting you change language, layout, and the common
guided toggles.
