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.
Claude Code
> /plugin marketplace add jarrodwatts/claude-hud> /plugin install claude-hud@claude-hud
GitHub Copilot
$ copilot plugin marketplace add jarrodwatts/claude-hud$ copilot plugin install claude-hud@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 | δΈζζζ‘£
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.
Prefer the terminal?
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.
Windows: setup says no JavaScript runtime was found
Install Node.js LTS (winget install OpenJS.NodeJS.LTS), restart your shell, and run /claude-hud:setup again.
Updates: Claude Code doesn't auto-update third-party plugins by default. To turn it on, run /plugin, open Marketplaces, select claude-hud, and choose Enable auto-update. If that option isn't there, or updates don't arrive, update by hand from the terminal:
claude plugin marketplace update claude-hud
claude plugin update claude-hud@claude-hud
Then run /reload-plugins in any open session. You don't need to run setup again.
The default is two lines:
[Opus] β my-project git:(main*)
Context ββββββββββ 45% β Usage ββββββββββ 25% (resets in 1h 30m)
Bedrock, Vertex, MiniMax), project path, and git branch.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
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.
/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).
| 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","cacheHitRate","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. sessionTokens isn't in the default order: add it to place the display.showSessionTokens summary like any other element, for example in a display.mergeGroups group with project. Left out, it stays on its own last line. cost works the same way: left out, the cost segment stays on the first line (where projectLineOrder can move it); added, it becomes its own element, for example "context","usage","cost" in elementOrder with ["context","usage","cost"] in display.mergeGroups puts it beside context and usage. |
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.showLaunchDir | boolean | false | Prefix the project path with the name of the directory Claude Code was launched in, when the shown path doesn't already include it (e.g. my-repo βΊ src). No effect with pathLevels: "full" |
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. Resets at local midnight. Independent of showCost |
display.showWeeklyCost | boolean | false | Show spend since the weekly quota window opened as Week $123.45, from the same ledger as showDailyCost. Subscribers only: needs the 7-day usage window |
display.showOutputStyle | boolean | false | Show the current output style as style: <name> |
display.showDuration | boolean | false | Show how long the session has been running, e.g. β±οΈ 5m |
display.showSpeed | boolean | false | Show the latest response's output speed out: 42.1 tok/s |
display.showUsage | boolean | true | Show Claude subscriber usage limits when available |
Stars on GitHub
View @jarrodwattsβs profileA personal Claude Code configuration bundling skills for planning with persistent markdown files, React useEffect and performance practices, coding standards, and UI design guideline reviews.
@jarrodwattsSee 12 claude-hud alternatives
Skills for running several coding agents together: an advisor for a second opinion, a committee for root cause analysis and planning, handoffs with full context, help with the Paseo app, and building local plugins.
@getpaseoGives you skills for pulling answers and prep from Circleback meeting notes, and for triaging failing GitHub Actions runs and GitHub issues. Use it to find what was decided, build meeting briefs, and sort CI failures and issues without digging through logs by hand.
@superset-shRuns and supervises teams of coding agents from planning through merge, handling CI feedback, review comments, and merge conflicts in isolated workspaces. Includes skills for launching the AO desktop app and triaging bug reports.
@untrivial-aiA Claude Code plugin that runs a multi-agent office of Claude Code and Codex style agents on your laptop or in sandboxes, using your existing subscriptions. It includes skills for Chinese article illustrations and rolling date-range queries.
@chaitanyagiriInstall it with the command on its page. Free and open source.
Is this plugin yours?
Claim it with GitHubSubmit a pluginPromote it