一个 Claude Code 插件，常驻在输入框下方，实时显示上下文用量、使用率限制、正在运行的工具、子代理以及待办进度。

🌐 English | 中文文档

在 Claude Code 中运行：

/plugin marketplace add jarrodwatts/claude-hud
/plugin install claude-hud
/reload-plugins
/claude-hud:setup

/claude-hud:setup 会把状态栏指向 HUD。Claude Code 会自动重新加载设置，HUD 会立即出现。想要自定义，直接告诉 Claude，或运行 /claude-hud:configure。

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

更新： 默认情况下，Claude Code 不会自动更新第三方插件。要开启自动更新，运行 /plugin，打开 Marketplaces，选择 claude-hud，然后选择 Enable auto-update。如果没有这个选项，或者收不到更新，可以在终端中手动更新：

claude plugin marketplace update claude-hud
claude plugin update claude-hud@claude-hud

然后在已打开的会话中运行 /reload-plugins。无需再次运行 setup。

默认显示两行：

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

• 第 1 行：模型、检测到时的提供商标签（Bedrock、Vertex、MiniMax）、项目路径和 git 分支。
• 第 2 行：上下文用量（随占用依次变为绿、黄、红）以及订阅用户的使用率限制。

可选行，通过 /claude-hud:configure 开启：

◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2        ← 工具
◐ explore [haiku]: Finding auth code (2m 15s)    ← 子代理
▸ Fix authentication bug (2/5)                   ← 待办

Claude HUD 是一个状态栏命令。Claude Code 通过 stdin 传入会话数据（模型、上下文窗口、费用、使用率限制、prompt cache）并显示它的输出。部分可选元素（例如工具、子代理和待办行）还会读取会话 transcript。不需要单独的窗口或 tmux，任何终端都能用。

/claude-hud:configure

引导流程涵盖布局、活动行、会话信息、使用率、git、语言和自定义行。保存前会预览改动，并保留它没有询问的所有设置。

其他设置位于 ~/.claude/plugins/claude-hud/config.json（或 $CLAUDE_CONFIG_DIR 下）。无效值会回退为默认值。

如果多个 CLAUDE_CONFIG_DIR 共用同一个 plugins/ 目录，可以把各目录专属的设置放进 $CLAUDE_CONFIG_DIR/claude-hud.json。它的结构相同，只需写要改的键，加载时叠加在共享配置之上：

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

标签语言支持英文（默认）、简体中文（zh-Hans，别名 zh）和繁体中文（zh-Hant，别名 zh-TW）。

颜色可以是名称（dim、red、green、yellow、magenta、cyan、brightBlue、brightMagenta）、256 色编号（0-255）或十六进制（#rrggbb）。colors.barFilled 和 colors.barEmpty 只接受单个可见字符；emoji 等宽字符在部分终端中可能影响进度条对齐。

只要 Claude Code 发送了订阅用户的 rate_limits（会话中首个响应之后），就会显示使用率。API key、Bedrock 和 Vertex 会话没有订阅用户限额，因此不显示。7 天窗口在超过 display.sevenDayThreshold 后出现：

Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (resets in 1h 30m) | Weekly █████████░ 85% (resets in 1d)

开启 display.usagePace 后，消耗快于恢复的窗口会变为琥珀色（预计用到 90% 及以上）或红色（预计在重置前用尽），并加上 ▲。已用低于 10% 的窗口保持中性。

外部快照。 display.externalUsagePath 读取一个本地 JSON 文件。stdin 没有窗口数据时由它补上，它的 balance_label 或 model_scoped 窗口（例如按模型的每周额度）会附加到 stdin 的数据上。路径必须是绝对路径，且文件要比 display.externalUsageFreshnessMs 新：

{
  "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" },
  "balance_label": "¥6.35",
  "model_scoped": [{ "display_name": "Fable", "utilization": 89, "resets_at": "2026-04-27T11:00:00Z" }]
}

display.externalUsageWritePath 则反过来：把 stdin 的使用率限制写入一个已存在目录中的私有 .json 文件，供其他工具读取。

display.showCost 显示 Claude Code 自己计算的会话费用（按标价，或使用你的 modelPricing 表）。Bedrock 和 Vertex 通过云服务商计费，因此除非同时设置 display.showRoutedCost，否则不显示它们的费用。

display.showDailyCost 会加上今天所有会话的花费（Today $12.34）。它记录在插件数据目录中的一个小账本里，在本地午夜重置，并从首次看到该会话的渲染开始计数。display.showWeeklyCost 使用同一个账本，从 7 天额度窗口的开始计数，因此需要订阅用户会话。

display.showPromptCache 显示主会话 prompt cache 何时失效，例如 Cache ⏱ until 14:30，或 expired。它显示时刻而不是倒计时：状态栏在两个回合之间不会重绘，而那正是缓存流失的时候；时刻无论渲染多旧都仍然正确。display.showCacheHitRate 显示从缓存读取的输入 token 占比。

把 jjStatus.enabled 设为 true，在含有 .jj 仓库的目录中会显示 jj 状态（例如 jj:(mybookmark*) 或 jj:(wrulwzyw !conflict)）而不是 git。HUD 以只读方式运行 jj，不会对工作副本做快照，因此脏标记反映的是 jj 最近一次快照。领先/落后计数和文件统计仅适用于 git。

{
  "lineLayout": "expanded",
  "pathLevels": 2,
  "gitStatus": { "showAheadBehind": true, "showFileStats": true },
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showDuration": true,
    "showCost": true
  },
  "colors": { "context": "cyan", "custom": "#FF6600" }
}

Claude Code 会在每条消息、/compact、权限或 vim 模式变化、使用率窗口重置以及 prompt cache 失效之后重新运行状态栏。若想在会话空闲时让倒计时和时长继续走动，在 ~/.claude/settings.json 的 statusLine 中加上 refreshInterval（秒）。

CLAUDE_HUD_DISABLE=1 claude

除 0、false、off、no 之外的任何值都会在该会话中清空 HUD，无需修改 settings.json。

Claude HUD 只在本地运行。它不发起网络请求，从不读取凭据，也不调用未公开的 API。它读取 Claude Code 的 stdin、会话 transcript、Claude 配置文件以及当前目录的 git 或 jj 元数据。它唯一写入的是 ~/.claude/plugins/claude-hud 下的少量状态文件（输出速度和费用账本），并使用私有权限。

--extra-cmd 会在每次刷新时运行一条 shell 命令，并把输出显示在第一行。除非 HUD 的环境中设置了 CLAUDE_HUD_ALLOW_EXTRA_CMD=1，否则它会被忽略。请把它视为任意代码执行，切勿使用来源不可信的命令。

HUD 没有出现。 发送一条消息，状态栏会在交互之后渲染。确认 shell 中没有设置 CLAUDE_HUD_DISABLE。如果 Node 或 Bun 的路径变了（例如 nvm 或 mise 升级之后），重新运行 /claude-hud:setup。

配置没有生效。 检查 JSON 是否有语法错误：无效文件会回退为默认值。确认取值在范围内，选项表中列出了各项范围。

没有显示使用率。 使用率需要以 Claude 订阅用户身份登录，并在首个响应之后出现。检查 display.showUsage。

没有 git 或 jj 状态。 确认当前位于仓库中，并且开启了 gitStatus.enabled（或 jjStatus.enabled，且 jj 在 PATH 中）。

缺少某个活动行。 工具、子代理、待办、技能和 MCP 行默认关闭，并且只在有活动时显示。

• Claude Code v2.1.260 或更高版本
• macOS 或 Linux：Node.js 18+ 或 Bun
• Windows：Node.js 18+

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

参见 CONTRIBUTING.md。

MIT，参见 LICENSE。