Claude HUD
A Claude Code plugin that shows what's happening: context usage, rate limits, active tools, running agents, and todo progress, always visible below your input.
🌐 English | 中文文档
Install
Inside Claude Code, run:
/plugin marketplace add jarrodwatts/claude-hud
/plugin install claude-hud
/reload-plugins
/claude-hud:setup
/claude-hud:setup points your status line at the HUD. Claude Code reloads settings on its own, so the HUD appears right away. To customize it, ask Claude or run /claude-hud:configure.
claude plugin marketplace add jarrodwatts/claude-hud
claude plugin install claude-hud@claude-hud
Then run /reload-plugins and /claude-hud:setup inside a session.
Install Node.js LTS (winget install OpenJS.NodeJS.LTS), restart your shell, and run /claude-hud:setup again.
What You See
The default is two lines:
[Opus] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (resets in 1h 30m)
- Line 1: model, a provider label when one is detected (
Bedrock,Vertex,MiniMax), project path, and git branch. - Line 2: context used (green, then yellow, then red as it fills) and your subscriber rate limits.
Optional lines, which you turn on with /claude-hud:configure:
◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2 ← tools
◐ explore [haiku]: Finding auth code (2m 15s) ← agents
▸ Fix authentication bug (2/5) ← todos
How It Works
Claude HUD is a status line command. Claude Code runs it with session data on stdin (model, context window, cost, rate limits, prompt cache) and shows what it prints. Some optional elements, such as the tools, agents, and todos lines, also read the session transcript. It needs no separate window or tmux and works in any terminal.
Configuration
/claude-hud:configure
The guided flow covers layout, activity lines, session info, usage, git, language, and a custom line. It previews the changes before saving and keeps every setting it doesn't ask about.
Everything else lives in ~/.claude/plugins/claude-hud/config.json (or under $CLAUDE_CONFIG_DIR). Invalid values fall back to their defaults.
If several CLAUDE_CONFIG_DIRs share one plugins/ directory, put per-directory settings in $CLAUDE_CONFIG_DIR/claude-hud.json. It uses the same shape, only needs the keys it changes, and is layered on top of the shared config:
{ "display": { "customLine": "Work Team" } }
Labels are available in English (the default), Simplified Chinese (zh-Hans, alias zh), and Traditional Chinese (zh-Hant, alias zh-TW).
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) |
showSeparators |
boolean | false | In compact layout, draw a rule between the session line and the activity lines |
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.showWorktree |
boolean | false | In a linked git worktree, show its name after the branch, e.g. git:(feat/x) ⎇ feat-x |
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.showProject |
boolean | true | Show the project path |
display.modelSource |
stdin | auto | transcript |
stdin |
Controls which source the model name comes from. stdin preserves the default behavior and always uses what Claude Code reports. auto opts into proxy redirect detection by using transcript models only for non-Claude models. transcript always uses the model from the API response. Transcript model values are terminal-sanitized and capped at 80 characters |
display.modelFormat |
full | compact | short |
full |
compact drops a context-window suffix such as (1M context); short also drops a leading Claude |
display.modelOverride |
string | "" |
Show this text instead of the model name (80 characters max) |
display.showProvider |
boolean | false | Show the provider label before the model name, e.g. [Bedrock | Opus 4.6]. Useful when a custom proxy serves identically-named models from different providers. When off, an auto-detected provider still trails the model as before |
display.providerName |
string | "" |
Explicit provider label used with display.showProvider, e.g. for a custom proxy that can't be auto-detected. Falls back to the auto-detected provider (Bedrock/Vertex/MiniMax/Enterprise) when empty; capped at 40 chars |
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.autoCompactWindow |
number | null |
null |
When set to a positive number such as 200000, compute the context percentage against this auto-compact window instead of the full model context window, matching the /context figure. Leave unset or null to preserve default full-window behavior. |
display.showConfigCounts |
boolean | false | Show CLAUDE.md, rules, MCPs, hooks counts |
display.environmentThreshold |
number | 0 | Hide the config counts until their total reaches this number (0 = always show) |
display.showCost |
boolean | false | Show the session cost Claude Code reports (cost.total_cost_usd) |
display.showRoutedCost |
boolean | false | Also show cost for Bedrock and Vertex sessions, which showCost hides because they bill through the cloud provider. Requires showCost |
display.showDailyCost |
boolean | false | Show today's cumulative spend across sessions as Today $12.34, accumulated from the native cost.total_cost_usd into a small per-day ledger in the plugin data directory. Reset |