On Windows, Node.js LTS is the recommended runtime for Claude HUD. If setup says no JavaScript runtime was found, install Node.js for your shell first:
Fair-code workflow automation platform with native AI capabilities. Combine visual building with custom code, self-host or cloud, 400+ integrations.
183,625
statusline
typescript
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 |
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, and threshold overrides. 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.
Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| language | en | zh | en | HUD label language. English is the default; set zh to enable Chinese labels. |
| lineLayout | string | expanded | Layout: expanded (multi-line) or compact (single line) |
| pathLevels | 1-3 | 1 | Directory levels to show in project path |
| elementOrder | string[] | ["project","context","usage","memory","environment","tools","agents","todos"] | Expanded-mode element order. Omit entries to hide them in expanded mode. |
| 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 |
| display.showModel | boolean | true | Show model name [Opus] |
| 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.usageBarEnabled | boolean | true | Display usage as visual bar instead of text |
| display.sevenDayThreshold | 0-100 | 80 | Show 7-day usage when >= threshold (0 = always) |
| 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 |
| display.showSessionName | boolean | false | Show session slug or custom title from /rename |
| display.showClaudeCodeVersion | boolean | false | Show the installed Claude Code version, e.g. CC v2.1.81 |
| display.showMemoryUsage | boolean | false | Show an approximate system RAM usage line in expanded layout |
| colors.context | color value | green | Base color for the context bar and context percentage |
| colors.usage | color value | brightBlue | Base color for usage bars and percentages below warning thresholds |
| colors.warning | color value | yellow | Warning color for context thresholds and usage warning text |
| colors.usageWarning | color value | brightMagenta | Warning color for usage bars and percentages near their threshold |
| colors.critical | color value | red | Critical color for limit-reached states and critical thresholds |
| colors.model | color value | cyan | Color for the model badge such as [Opus] |
| colors.project | color value | yellow | Color for the project path |
| colors.git | color value | magenta | Color for git wrapper text such as git:( and ) |
| colors.gitBranch | color value | cyan | Color for the git branch and branch status text |
| colors.label | color value | dim | Color for labels and secondary metadata such as Context, Usage, counts, and progress text |
| colors.custom | color value | 208 | Color for the optional custom line |
Supported color names: dim, red, green, yellow, magenta, cyan, brightBlue, brightMagenta. You can also use a 256-color number (0-255) or hex (#rrggbb).
display.showMemoryUsage is fully opt-in and only renders in expanded layout. It reports approximate system RAM usage from the local machine, not precise memory pressure inside Claude Code or a specific process. The number may overstate actual pressure because reclaimable OS cache and buffers can still be counted as used memory.
display.showCost is fully opt-in. ClaudeHUD prefers the native cost.total_cost_usd field that Claude Code provides on stdin when it is available. If that field is absent or invalid for a direct Anthropic session, ClaudeHUD falls back to the existing local transcript-based estimate so the cost line still works on older payloads. The native field is absent before
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
