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 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
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.
Chinese HUD labels are available as an explicit opt-in. English stays the default unless you choose 中文 in /claude-hud:configure or set language in config. The short zh alias remains valid, and new guided config writes the canonical zh-Hans value.
Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| language | en | zh | zh-Hans | en | HUD label language. English is the default; set zh or zh-Hans to enable Simplified Chinese labels. |
| lineLayout | string | expanded | Layout: expanded (multi-line) or compact (single line) |
| pathLevels | 1-3 | 1 | Directory levels to show in project 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","context","usage","promptCache","memory","environment","tools","agents","todos","sessionTime"] | Expanded-mode element order. Omit entries to hide them in expanded mode. Existing configs keep their explicit order until updated. |
| display.mergeGroups | string[][] | [["context","usage"]] | Expanded-mode groups that should share a line when adjacent. Set [] to disable merged lines. |
| 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 |
| display.showModel | boolean | true | Show model name [Opus] |
| display.showAddedDirs | boolean | true | Show extra workspace directories from /add-dir (e.g. +sparkle +lib-foo); empty array renders nothing. In both layouts at most 5 dirs render (overflow shown as +N more) and basenames are truncated to 24 chars with … |
| display.addedDirsLayout | inline | line | inline | inline puts dirs next to the project name with a +name prefix per dir; line renders them on a separate Added dirs: name1, name2 line (no + prefix, comma-separated) |
| display.showContextBar | boolean | true | Show visual context bar ████░░░░░░ |
| display.contextValue | percent | tokens | remaining | both | percent | Context display format (45%, 45k/200k, 55% remaining, or 45% (45k/200k)) |
| display.showConfigCounts | boolean | false | Show CLAUDE.md, rules, MCPs, hooks counts |
| display.showCost | boolean | false | Show session cost using Claude Code's native cost.total_cost_usd when available, with a local estimate fallback for direct Anthropic sessions |
| display.showOutputStyle | boolean | false | Show the active Claude Code outputStyle from settings files as style: <name> |
| display.showDuration | boolean | false | Show session duration ⏱️ 5m |
| display.showSpeed | boolean | false | Show output token speed out: 42.1 tok/s |
| display.showUsage | boolean | true | Show Claude subscriber usage limits when available |
| display.usageValue | percent | remaining | percent | Usage display format (25% used, or 75% remaining) |
| display.usageBarEnabled | boolean | true | Display usage as visual bar instead of text |
| display.usageCompact | boolean | false | Display usage in a shorter text form such as 5h: 25% (1h 30m); takes precedence over display.usageBarEnabled |
| display.showResetLabel | boolean | true | Show the resets in prefix before usage countdowns |
| display.timeFormat | relative | absolute | both | relative | How reset times are shown in usage windows: countdown only (resets in 2h 30m), wall-clock time (resets at 14:30), or both (resets in 2h 30m, at 14:30) |
| display.sevenDayThreshold | 0-100 | 80 | Show 7-day usage when >= threshold (0 = always) |
| display.externalUsagePath | string | "" | Optional path to a local usage snapshot file used only when stdin rate_limits are missing |
| display.externalUsageFreshnessMs | number | 300000 | Maximum allowed age for the external usage snapshot before it is ignored |
| display.showTokenBreakdown | boolean | true | Show token details at high context (85%+) |
| display.showTools | boolean | false | Show tools activity line |
| display.showAgents | boolean | false | Show agents activity line |
| display.showTodos | boolean | false | Show todos progress line |
| `dis