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 | 中文文档

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.

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.

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