jarrodwatts/claude-hud: A Claude Code plugin that shows what's happening - context usage, active tools, running agents, and todo progress

摘要LLM 归库摘要

• 核心内容： claude-hud 是一款 Claude Code 状态栏插件，实时显示上下文使用率、工具活动、子代理状态和待办进度。支持通过 /plugin 命令安装，通过 /claude-hud:setup 和 /claude-hud:configure 配置布局、语言、颜色和显示元素。
• 可复用知识： Claude Code 的插件机制（/plugin marketplace add + /plugin install）与状态栏 API 工作方式；HUD 预设（Full/Basic/Minimal）和各项配置参数（颜色、布局、元素顺序、Git 状态、速率限制显示等）。
• 关联页面建议： 04 AI_API与自动化库/02_wiki/claude_code/、04 AI_API与自动化库/02_wiki/skills/
• 下一步处理： 可在 Claude Code 中试用 /claude-hud:setup 完成安装与配置，体验上下文可视化监控与代理跟踪功能。
• 归库说明： 分类到 04 AI_API与自动化库，置信度 0.85，理由为 Claude Code 插件安装/配置文档，属于 AI 开发工具生态。

克劳德·胡德#

一款 Claude Code 插件，可显示当前正在发生的事情——上下文使用情况、活动工具、正在运行的代理以及待办事项进度。始终显示在输入框下方。

🌐 English | 中文文档

安装#

在 Claude Code 实例中，运行以下命令：

步骤 1：添加市场

/plugin marketplace add jarrodwatts/claude-hud

步骤 2：安装插件

Linux 用户：请先点击此处

On Linux, /tmp is often a separate filesystem (tmpfs), which causes plugin installation to fail with:

EXDEV: cross-device link not permitted

Fix: Set TMPDIR before installing:

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

Then run the install command below in that session. This is a Claude Code platform limitation.

/plugin install claude-hud

之后，重新加载插件：

/reload-plugins

步骤 3：配置状态栏

/claude-hud:setup

⚠️ Windows 用户：如果安装程序提示未找到 JavaScript 运行时，请点击此处。

On Windows, Node.js LTS is the supported runtime for Claude HUD setup. If setup says no JavaScript runtime was found, install Node.js for your shell first:

winget install OpenJS.NodeJS.LTS

Then restart your shell and run /claude-hud:setup again.

完成！重启 Claude Code 以加载新的 statusLine 配置，然后 HUD 就会出现。

在 Windows 系统上，安装程序写入新的 statusLine 配置后，需要完全重启 Claude Code。

---

什么是 Claude HUD？#

Claude HUD 让您更好地了解 Claude Code 会话中正在发生的事情。

你所看到的#

默认值（2 行）#

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

• 第 1 行 — 模型、提供者标签（如果已明确识别，例如 Bedrock 、 Vertex ）、项目路径、Git 分支
• 第 2 行 — 上下文栏（绿色 → 黄色 → 红色）和使用速率限制

可选行（通过 /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

---

工作原理#

Claude HUD 使用 Claude Code 的原生 状态栏 API—— 无需单独的窗口，无需 tmux，可在任何终端中使用。

Claude Code → stdin JSON → claude-hud → stdout → displayed in your terminal
           ↘ transcript JSONL (tools, agents, todos)

主要特点：

• 来自 Claude Code 的原生令牌数据（非估算值）
• 与 Claude Code 报告的上下文窗口大小相匹配，包括最新的 100 万上下文会话
• 解析转录文本中的工具/代理活动
• 每隔 1001 300 毫秒更新一次

---

配置#

随时自定义您的 HUD：

/claude-hud:configure

引导流程负责布局、语言和常用显示切换。高级设置（例如自定义颜色和阈值）也保留在其中，但您需要直接编辑配置文件进行设置：

• 首次设置 ：选择一个预设（完整/基本/极简），选择标签语言，然后微调各个元素
• 随时自定义 ：切换项目显示/隐藏、调整 Git 显示样式、切换布局或更改标签语言
• 保存前预览 ：在提交更改前，准确查看 HUD 的外观。

预设#

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. The short zh alias remains valid, and new guided config writes the canonical zh-Hans value.

Options#

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.

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.

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. 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, plus a five_hour window, seven_day window, or balance_label. balance_label is optional text for prepaid provider balances; it is trimmed, length-limited, and sanitized before display. Invalid JSON, stale files, or invalid timestamps are ignored quietly.

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.

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", "sessionTime"],
  "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

---