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

EXDEV: cross-device link not permitted

mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude

/plugin install claude-hud

After that, reload plugins:

/reload-plugins

Step 3: Configure the statusline

/claude-hud:setup

winget install OpenJS.NodeJS.LTS

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

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

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.

Options

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 first API response in a session, so the cost display may stay hidden until then. ClaudeHUD also keeps the cost hidden for known routed providers such as Bedrock and Vertex AI, because cloud-provider billed sessions may report $0.00 or omit the field even though the session was not literally free.

display.showPromptCache is fully opt-in. When enabled, ClaudeHUD looks at the timestamp of the last assistant response in the local transcript and shows a live countdown until the prompt cache expires. The default TTL is 5 minutes (300 seconds). Set display.promptCacheTtlSeconds to 3600 if you want a 1-hour Max-style window. If the transcript does not have an assistant timestamp yet, the cache element stays hidden.

Usage Limits

Usage display is enabled by default when Claude Code provides subscriber rate_limits data on stdin. It shows your rate limit consumption on line 2 alongside the context bar.

ClaudeHUD prefers the official statusline stdin payload. If rate_limits are missing, you can opt into a local sidecar fallback by setting display.externalUsagePath to a JSON snapshot written by another tool such as a proxy. Stdin still wins whenever both sources exist.

The fallback snapshot must be fresh enough (display.externalUsageFreshnessMs) and include valid updated_at, five_hour, and/or seven_day fields. Invalid JSON, stale files, or invalid timestamps are ignored quietly.

Free/weekly-only accounts render the weekly window by itself instead of showing a ghost 5h: -- placeholder.

The 7-day percentage appears when above the display.sevenDayThreshold (default 80%):

Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h) | ██████████ 85% (2d / 7d)

To disable, set display.showUsage to false.

Reset times use relative countdowns by default. Set display.timeFormat to absolute for wall-clock times or both to show both forms. This setting is manual-only today; /claude-hud:configure preserves it without editing it.

Set display.showResetLabel to false if you want shorter usage countdowns such as (3h 17m) instead of (resets in 3h 17m).

Set display.usageCompact to true if you want the shorter usage-only form, for example 5h: 25% (1h 30m). Compact usage takes precedence over display.usageBarEnabled.

Requirements:

• Claude Code must include subscriber rate_limits data on stdin for the current session
• Not available for API-key-only users

Troubleshooting: If usage doesn't appear:

• Ensure you're logged in with a Claude subscriber account (not API key)
• Check display.showUsage is not set to false in config
• API users see no usage display (they have pay-per-token, not rate limits)
• AWS Bedrock models display Bedrock and hide usage limits (usage is managed in AWS)
• Google Vertex AI models display Vertex and hide cost estimates (pricing differs from Anthropic direct)
• Claude Code may leave rate_limits empty until after the first model response in a session
• Some Claude Code builds and subscription tiers may still omit rate_limits, even after the first response
• If you configured display.externalUsagePath, ClaudeHUD will try that local snapshot before hiding usage
• ClaudeHUD never falls back to credential scraping or undocumented API calls

Example fallback snapshot:

{
  "updated_at": "2026-04-20T12:00:00.000Z",
  "five_hour": {
    "used_percentage": 42,
    "resets_at": "2026-04-20T15:00:00.000Z"
  },
  "seven_day": {
    "used_percentage": 84,
    "resets_at": "2026-04-27T12:00:00.000Z"
  }
}

Example Configuration

{
  "language": "zh",
  "lineLayout": "expanded",
  "pathLevels": 2,
  "elementOrder": ["project", "tools", "context", "usage", "memory", "environment", "agents", "todos"],
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": true
  },
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showConfigCounts": true,
    "showDuration": true,
    "showMemoryUsage": true
  },
  "colors": {
    "context": "cyan",
    "usage": "cyan",
    "warning": "yellow",
    "usageWarning": "magenta",
    "critical": "red",
    "model": "cyan",
    "project": "yellow",
    "git": "magenta",
    "gitBranch": "cyan",
    "label": "dim",
    "custom": "#FF6600"
  }
}

Display Examples

1 level (default): [Opus] │ my-project git:(main)

2 levels: [Opus] │ apps/my-project git:(main)

3 levels: [Opus] │ dev/apps/my-project git:(main)

With dirty indicator: [Opus] │ my-project git:(main*)

With ahead/behind: [Opus] │ my-project git:(main ↑2 ↓1)

With file stats: [Opus] │ my-project git:(main* !3 +1 ?2)

• ! = modified files, + = added/staged, ✘ = deleted, ? = untracked
• Counts of 0 are omitted for cleaner display

Troubleshooting

Config not applying?

• Check for JSON syntax errors: invalid JSON silently falls back to defaults
• Ensure valid values: pathLevels must be 1, 2, or 3; lineLayout must be expanded or compact; maxWidth must be a positive number
• Delete config and run /claude-hud:configure to regenerate

Git status missing?

• Verify you're in a git repository
• Check gitStatus.enabled is not false in config

Tool/agent/todo lines missing?

• These are hidden by default — enable with showTools, showAgents, showTodos in config
• They also only appear when there's activity to show

HUD not appearing after setup?

• Restart Claude Code so it picks up the new statusLine config
• On macOS, fully quit Claude Code and run claude again in your terminal

Requirements

• Claude Code v1.0.80+
• macOS/Linux: Node.js 18+ or Bun
• Windows: Node.js 18+

Development

git clone https://github.com/jarrodwatts/claude-hud
cd claude-hud
npm ci && npm run build
npm test

See CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE

Star History