jarrodwatts/claude-hudPublic

A Claude Code plugin that shows what's happening — context usage, active tools, running agents, and todo progress. Always visible below your input.

🌐 English | 中文文档

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 (no restart needed):

/reload-plugins

claude plugin marketplace add jarrodwatts/claude-hud
claude plugin install claude-hud@claude-hud

Step 3: Configure the statusline

/claude-hud:setup

winget install OpenJS.NodeJS.LTS

Done! Claude Code reloads settings automatically — the HUD appears after your next message, no restart needed. If it doesn't show up, restart Claude Code (older versions require a restart to pick up statusLine changes).

Claude HUD gives you better insights into what's happening in your Claude Code session.

[Opus] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)

• Line 1 — Model, provider label when positively identified (for example Bedrock, Vertex, MiniMax), project path, git branch
• Line 2 — Context bar (green → yellow → red) and usage rate limits

◐ 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

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
• Re-renders after each interaction (new assistant messages, /compact, permission changes, vim-mode toggles), debounced at 300ms

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

After choosing a preset, you can turn individual elements on or off.

Edit ~/.claude/plugins/claude-hud/config.json directly for advanced settings such as colors.*, pathLevels, maxWidth, threshold overrides, display.timeFormat, display.hourCycle, and display.promptCacheTtlSeconds. Running /claude-hud:configure preserves those manual settings while still letting you change language, layout, and the common guided toggles.

If you run several Claude config directories via CLAUDE_CONFIG_DIR and symlink plugins/ to a shared location, plugins/claude-hud/config.json is the same physical file for all of them. Put per-directory settings in $CLAUDE_CONFIG_DIR/claude-hud.json instead - it uses the same shape, only needs the keys it changes, and is layered on top of the shared config at load time:

For example, put this in ~/.config/claude/work/claude-hud.json:

{ "display": { "customLine": "Work Team" } }

Simplified and Traditional Chinese HUD labels are available as explicit opt-ins. English stays the default unless you choose a Chinese locale in /claude-hud:configure or set language in config. The zh alias maps to Simplified Chinese, and zh-TW maps to Traditional Chinese. Guided config writes the canonical zh-Hans or zh-Hant value.

colors.barFilled and colors.barEmpty accept a single visible grapheme. Control characters, invisible format characters (bidi controls, zero-width joiners, variation selectors), line/paragraph separators, and noncharacters are rejected. Wide characters (emoji, CJK) may affect bar alignment depending on the terminal.

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. Set display.showRoutedCost: true (alongside showCost) to opt into cost for those providers anyway: the native cost.total_cost_usd is shown as Cost when positive, otherwise ClaudeHUD falls back to a token-based Est. from the Anthropic pricing table.

display.showDailyCost is fully opt-in and answers a different question than showCost: what has the whole day cost across sessions, not just the current conversation. On each render ClaudeHUD folds the native cost.total_cost_usd into a small daily-cost.json ledger in the plugin data directory, keyed by session_id, and shows the day's cumulative spend as Today $12.34. The first sighting of a session records a baseline so only spend from that point counts, the counter resets at local midnight, sessions spanning midnight contribute only the current day's part, and entries unseen for more than 24 hours are dropped so the file stays bounded. It only uses the native field (no estimate fallback), so sessions that never render the statusline are not counted, counting starts when the option is enabled, and totals are per machine. Routed providers (Bedrock/Vertex) are excluded unless display.showRoutedCost is also enabled, matching showCost.

Official MiniMax Anthropic-compatible endpoints receive a MiniMax provider label. MiniMax M2.7 can use its published token and cache prices for local estimates; M3 pricing depends on each request's context tier, which cumulative session tokens cannot safely infer, so ClaudeHUD does not guess an M3 estimate.

display.showPromptCache is fully opt-in. When enabled, ClaudeHUD shows the wall-clock time the session's prompt cache expires (e.g. Cache ⏱ until 14:30), or expired once that time has passed. It follows display.hourCycle and display.showClockSeconds like every other clock time in the HUD. If the transcript has no main-session response yet, the cache element stays hidden.

It shows an expiry time rather than a countdown because the statusline only repaints while Claude Code is active. Between turns — exactly when the cache is draining — a countdown freezes at whatever it last displayed and keeps reporting it; a clock time stays true no matter how stale the render is.

ClaudeHUD detects the cache tier from the transcript when possible. The existing display.promptCacheTtlSeconds setting remains a fallback for older or proxied transcripts that do not expose tier details:

• The TTL is detected. Every cache write records the tier it used (usage.cache_creation.ephemeral_5m_input_tokens vs ephemeral_1h_input_tokens), so a 1-hour session counts down against an hour, and a session that changes tier mid-run is followed. Detected values take precedence over the configured fallback.
• The clock starts at the request, not at the response it produced, because that is when the cache is read or written. Anchoring on the response would hand the session however long that response took to generate.
• Subagent responses are ignored. A subagent runs against its own cache and does not refresh the main session's.

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.

Set display.usageValue to remaining to show quota left instead of quota used. Warning colors and 7-day threshold checks still use the underlying used percentage.

ClaudeHUD prefers the official statusline stdin payload for rate-limit windows. If display.externalUsagePath points to a fresh local sidecar snapshot, ClaudeHUD can append its balance_label alongside stdin windows. If stdin rate_limits are missing, the same snapshot can provide fallback usage windows.

The fallback snapshot path must be absolute. The snapshot must be fresh enough (display.externalUsageFreshnessMs) and include valid updated_at, plus a five_hour window, seven_day window, balance_label, or model_scoped array. balance_label is optional text for prepaid provider balances; it is trimmed, length-limited, and sanitized before display. Relative paths, invalid JSON, stale files, or invalid timestamps are ignored quietly.

The snapshot may also carry model_scoped windows using the same shape Claude Code defines for stdin (display_name, utilization on the 0-100 scale, ISO resets_at). They render exactly like stdin scoped windows (see the model-scoped usage section) and stdin always wins when it carries its own model_scoped data. This lets a local feeder surface per-model weekly quotas (e.g. Fable) that the statusline payload does not include yet:

{
  "updated_at": "2026-07-24T14:12:37Z",
  "model_scoped": [
    { "display_name": "Fable", "utilization": 89, "resets_at": "2026-07-27T11:00:00Z" }
  ]
}

One zero-credential way to produce such a snapshot is Claude Code's own get_usage control request, which returns rate_limits.model_scoped without spending tokens; a scheduled job can pipe it through jq into the snapshot file. The HUD itself never fetches anything: it only reads the file.

Set display.externalUsageWritePath if you want ClaudeHUD to write the official stdin rate_limits into a local snapshot for other tools. The path must be absolute, end in .json, and live in an existing directory. ClaudeHUD writes the file with private permissions and ignores invalid paths 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, both to show both forms, elapsed to show how far through each usage window you are, or elapsedAndAbsolute to show elapsed window progress plus the wall-clock reset time. This setting is manual-only today; /claude-hud:configure preserves it without editing it.

Wall-clock reset times (absolute/both/elapsedAndAbsolute) default to your system locale for 12- vs 24-hour formatting. Set display.hourCycle to h23 to force 24-hour time regardless of locale, or to h12/h11 to force 12-hour time with AM/PM. Set display.showClockSeconds to true to include seconds in the wall-clock time, e.g. at 14:30:07.

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.

Set display.showModelScopedUsage to false to hide the per-model weekly windows (e.g. Fable). The usage line then renders exactly as it would for an account that has none: the 5h/7d windows stay, snapshot windows are hidden along with the stdin ones, and a hidden window no longer counts toward a configured usage threshold, so it can no longer keep the line on screen by itself.

ClaudeHUD is local-only by design. It does not make network requests, scrape credentials, or call undocumented Claude APIs. It reads the statusline JSON from stdin, the current session transcript path supplied by Claude Code, selected Claude configuration files under ~/.claude, and git metadata for the current workspace.

HUD cache files are written under ~/.claude/plugins/claude-hud with private permissions on POSIX filesystems. The cache stores derived display metadata such as context percentages, token counters, activity names, and the resolved Claude Code version.

--extra-cmd is disabled unless CLAUDE_HUD_ALLOW_EXTRA_CMD=1 (or true, yes, on) is present in the HUD process environment. Treat this option as arbitrary code execution: it runs the supplied shell command with your user privileges on statusline refreshes. Do not use commands copied from untrusted sources.

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)
• Bedrock and Vertex AI models hide cost estimates by default (billing differs from Anthropic direct); opt in with display.showRoutedCost
• 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"
  }
}

{
  "language": "zh",
  "lineLayout": "expanded",
  "pathLevels": 2,
  "elementOrder": ["project", "tools", "skills", "mcp", "context", "usage", "memory", "environment", "agents", "todos", "sessionTime"],
  "projectLineOrder": ["project", "model"],
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": true
  },
  "jjStatus": {
    "enabled": true,
    "showDirty": true,
    "showConflicts": true
  },
  "display": {
    "showTools": true,
    "showSkills": true,
    "showMcp": 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"
  }
}

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

Set jjStatus.enabled to true to opt in. When a real .jj directory is found in (or above) the working directory, the HUD shows jj-native status instead of git — the two are mutually exclusive per invocation, even in a colocated jj+git repo. If jj cannot be queried safely, a colocated repository falls back to its existing git status.

With a bookmark: [Opus] │ my-project jj:(mybookmark)

Anonymous change (no bookmark at @): [Opus] │ my-project jj:(wrulwzyw)

Dirty working copy: [Opus] │ my-project jj:(mybookmark*)

Unresolved conflict: [Opus] │ my-project jj:(mybookmark !conflict)

Ahead/behind counts and per-file change stats are git-only in this version — jj's equivalent requires more expensive revset queries against remote_bookmarks(), so they're left out to keep the jj status fetch to a single subprocess call.

The HUD runs jj in prompt-safe, read-only mode: it disables the pager, ignores the live working copy, and reads the current operation without reconciling it. That avoids snapshotting files or mutating repository state during statusline refreshes. As a result, the dirty marker reflects jj's most recent working-copy snapshot and can remain stale until another jj command records new changes.

Claude Code only re-runs the statusline after an interaction (a new assistant message, /compact finishing, a permission-mode change, or a vim-mode toggle), so time-based HUD info — session duration, usage reset countdowns, the prompt-cache countdown — goes stale between messages. To keep it ticking, add refreshInterval (seconds, minimum 1) to the statusLine entry in ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "...",
    "refreshInterval": 5
  }
}

/claude-hud:setup offers this during installation. Each refresh re-runs the HUD command, so 5 seconds is a good default; use 1 second only if you want visibly smooth countdowns.

Set the CLAUDE_HUD_DISABLE environment variable to launch a session without the HUD — no need to remove the statusLine entry from settings.json:

CLAUDE_HUD_DISABLE=1 claude

Leaving it unset (or setting an explicit negative: 0, false, off, no) keeps the HUD enabled. When disabled, the HUD exits immediately without reading the transcript or running git, so the statusline simply stays empty for that session.

Config not applying?

• Check for JSON syntax errors: invalid JSON silently falls back to defaults
• Ensure valid values: pathLevels must be 1, 2, 3, or full; 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

jj status missing, or seeing git:(...) in a jj repo?

• Verify a .jj directory exists at or above the working directory
• Set jjStatus.enabled to true in config (jj support is opt-in)
• Verify the jj binary is installed and on PATH

Tool/skill/MCP/agent/todo lines missing?

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

HUD not appearing after setup?

• Send any message — settings reload automatically, but the statusline only renders after your next interaction
• If it still doesn't appear, restart Claude Code (fully quit and run claude again) — older Claude Code versions require a restart to pick up statusLine changes
• Make sure CLAUDE_HUD_DISABLE is not set in your environment (e.g. exported from a shell profile) — it silences the HUD entirely, including setup verification

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

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

See CONTRIBUTING.md for guidelines.

MIT — see LICENSE