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
On older Claude Code versions, /tmp being a separate filesystem (tmpfs) caused plugin installation to fail with:
EXDEV: cross-device link not permitted
This Claude Code bug has since been fixed — if you hit it, update Claude Code first. If you can't update, set TMPDIR before installing:
mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude
Then run the install command below in that session.
/plugin install claude-hud
After that, reload plugins (no restart needed):
/reload-plugins
Steps 1–2 can also be done outside a session with the Claude Code CLI:
claude plugin marketplace add jarrodwatts/claude-hud
claude plugin install claude-hud@claude-hud
Then run /reload-plugins inside your session (or start a new one).
Step 3: Configure the statusline
/claude-hud:setup
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! Claude Code reloads settings automatically — the HUD appears after your next message, no restart needed. If it doesn't show up, restart Claude Code (older versions require a restart to pick up statusLine changes).
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,MiniMax), 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
- Re-renders after each interaction (new assistant messages,
/compact, permission changes, vim-mode toggles), debounced at 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, display.hourCycle, and display.promptCacheTtlSeconds. Running /claude-hud:configure
preserves those manual settings while still letting you change language, layout, and the common
guided toggles.
If you run several Claude config directories via CLAUDE_CONFIG_DIR and symlink plugins/ to a
shared location, plugins/claude-hud/config.json is the same physical file for all of them. Put
per-directory settings in $CLAUDE_CONFIG_DIR/claude-hud.json instead - it uses the same shape,
only needs the keys it changes, and is layered on top of the shared config at load time:
For example, put this in ~/.config/claude/work/claude-hud.json:
{ "display": { "customLine": "Work Team" } }
Simplified and Traditional Chinese HUD labels are available as explicit opt-ins. English stays the default unless you choose a Chinese locale in /claude-hud:configure or set language in config. The zh alias maps to Simplified Chinese, and zh-TW maps to Traditional Chinese. Guided config writes the canonical zh-Hans or zh-Hant value.
Options
| Option | Type | Default | Description |
|---|---|---|---|
language |
en | zh | zh-Hans | zh-Hant | zh-TW |
en |
HUD label language. Use zh or zh-Hans for Simplified Chinese and zh-Hant or zh-TW for Traditional Chinese. |
lineLayout |
string | expanded |
Layout: expanded (multi-line) or compact (single line) |
pathLevels |
1-3 | full |
1 | Directory levels to show in project path, or full to show the entire absolute path |
maxWidth |
number | null |
null |
Optional fallback width used only when terminal width detection fails completely |
forceMaxWidth |
boolean | false | Always use maxWidth when it is set, even if terminal width detection returns a smaller value |
elementOrder |
string[] | ["project","addedDirs","context","usage","promptCache","memory","environment","tools","skills","mcp","agents","todos","sessionTime"] |
Expanded-mode element order. Omit entries to hide them in expanded mode. Existing configs keep their explicit order until updated. |
projectLineOrder |
string[] | [] |
Optional leading order of segments within the first line, in both layouts. Visibility stays with the display.show* flags, and omitted segments retain their existing renderer order. model covers provider + model + effort (plus the context bar in compact mode); project covers path + added dirs + git as one segment. Example: ["project","model"] puts the project/git block before the model badge. |
display.mergeGroups |
string[][] | [["context","usage"]] |
Expanded-mode groups that should share a line when adjacent. Set [] to disable merged lines. |
display.rightAlign |
string[] | [] |
Starts a right-aligned suffix at the first listed element in a merged row, preserving elementOrder and padding the gap with spaces. Requires the anchor to be in a display.mergeGroups group that actually renders on one line. Ignored when the terminal width is unknown, the anchor is first, or there is no room for padding. Example: ["context"] with a ["project","context","usage"] group keeps project/git left and pins context + usage right. |
gitStatus.enabled |
boolean | true | Show git branch in HUD |
gitStatus.showDirty |
boolean | true | Show * for uncommitted changes |
gitStatus.showAheadBehind |
boolean | false | Show ↑N ↓N for ahead/behind remote |
gitStatus.pushWarningThreshold |
number | 0 | Color the ahead count with the warning color at or above this unpushed-commit count (0 disables it) |
gitStatus.pushCriticalThreshold |
number | 0 | Color the ahead count with the critical color at or above this unpushed-commit count (0 disables it) |
gitStatus.showFileStats |
boolean | false | Show file change counts !M +A ✘D ?U |
gitStatus.branchOverflow |
truncate | wrap |
truncate |
Keep current truncation behavior or let the git block wrap onto its own line boundary when possible |
jjStatus.enabled |
boolean | false | Opt in to jj (Jujutsu) status. When enabled and a real .jj directory is found, jj is used instead of git for that repo — never both |
jjStatus.showDirty |
boolean | true | Show * when the working-copy commit differs from its parent |
jjStatus.showConflicts |
boolean | true | Show a !conflict marker when the working-copy commit has an unresolved conflict |
display.showModel |
boolean | true | Show model name [Opus] |
display.modelSource |
stdin | auto | transcript |
stdin |
Controls which source the model name comes from. stdin pr |