Claude HUD 状态栏插件：让 Claude Code 上下文用量与 Agent 状态一目了然

May 11, 2026

如果你经常使用 Claude Code，大概率经历过这些场景：对话进行中，回复质量突然下滑，回过神来才发现上下文窗口已快塞满；或者任务跑到一半毫无征兆地被限流，这才意识到 5 小时的用量额度已消耗殆尽。更令人心里没底的是，Claude 在后台到底在做什么——哪些子 Agent 在跑、工具调用到了哪一步、Todo 完成了多少，你几乎一无所知，除非死死盯住终端上一行行的日志。

许多人在第一次装好这个插件后，都会不约而同地感叹：为什么没有早点装。

Claude HUD 是一款 Claude Code 的状态栏增强插件，它做的事情简单直接：在输入框下方实时展示上下文使用率、用量额度、工具调用、子 Agent 状态与 Todo 进度。装上之后，你不必敲任何命令，这些信息就能一目了然。

项目地址：https://github.com/jarrodwatts/claude-hud。

Claude HUD 展示的关键状态一览

安装完成后，Claude HUD 默认会在你的输入框下方显示两行状态信息：

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

第一行：当前模型名称（如 Opus）、服务商标识（如 Bedrock）、项目路径、Git 分支
第二行：上下文窗口使用率（带颜色进度条，绿→黄→红渐变）、订阅用量额度与剩余时间

你还可以通过配置开启额外的信息行：

◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2        ← 工具活动  
◐ explore [haiku]: Finding auth code (2m 15s)    ← Agent 状态  
▸ Fix authentication bug (2/5)                   ← Todo 进度

这些信息为什么值得关注？因为 Claude Code 默认不会主动告诉你“我快忘了之前聊过什么”或者“你的额度快用完了”。HUD 把这些关键指标变成了直观的视觉信号：上下文进度条一旦从绿变黄再变红，就是最明确的 /compact 提醒；项目路径和 Git 分支让你在多个项目间切换不会搞混；工具和 Agent 那几行回答的是“Claude 此刻在干什么”——不再需要去翻日志，状态栏直接替你报出进展。

安装流程与注意事项

系统要求：

要求	说明
Claude Code	v1.0.80+
运行时	Node.js 18+ 或 Bun
操作系统	macOS / Linux / Windows

安装总共只需三条命令，在 Claude Code 中依次执行即可。

关键提醒：第二步完成后一定要执行 /reload-plugins，否则下一步会直接报 Unknown skill 错误。这是常见的踩坑点。

第一步：添加插件市场

/plugin marketplace add jarrodwatts/claude-hud

第二步：安装插件

/plugin install claude-hud

安装结束后，执行 /reload-plugins 重新加载插件（前面已经强调过，这一步很容易忘）。

第三步：配置状态栏

/claude-hud:setup

setup 过程会让你选择要开启哪些信息行：

1. Tools activity— 建议勾选。实时显示 Claude 在读文件、编辑文件还是搜索代码，不用盯着日志看。
2. Agents & Todos— 建议勾选。显示子 Agent 运行状态和任务完成进度，跑复杂任务时很有用。
3. Session info— 可选。显示会话时长和 CLAUDE.md、MCP 等配置数量，对调试环境配置有帮助。
4. Session name— 一般不需要。除非你经常用 /rename 给会话起名字。
1. 自定义行 — 不需要填，直接跳过即可。

选择完毕后，重启 Claude Code（这步不能省，因为状态栏配置是在启动时加载的）。

重启后，你就能在输入框下方看到 HUD 状态栏了。

Linux 用户特别说明

Linux 上 /tmp 通常是独立的 tmpfs 文件系统，安装时会报 EXDEV: cross-device link not permitted 错误。解决方法：

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

在这个会话中执行安装命令即可。

Windows 用户须知

如果 setup 提示找不到 JavaScript 运行时，需要先安装 Node.js：

winget install OpenJS.NodeJS.LTS

然后重启终端，重新执行 /claude-hud:setup。

工作原理细解

搞清楚它是怎么拿到数据的，你才能判断显示的信息是否可靠。

Claude Code 本身提供了一个叫 statusLine 的原生能力（你可以在 ~/.claude/settings.json 里配置，也可以用 /statusline 命令生成）。它的机制很简单：Claude Code 把当前会话的 JSON 数据（模型名称、Token 用量、上下文窗口百分比、订阅额度等）通过 stdin 管道喂给你指定的脚本，脚本解析后把要显示的内容打印到 stdout，Claude Code 再把输出渲染在终端底部的状态栏上。刷新频率大约每 300ms 一次。

你当然可以自己写一个 shell 脚本来完成这件事，但多数人并不想折腾 jq 解析和 ANSI 颜色码。Claude HUD 本质上就是帮你把这个脚本写好了——它注册为 statusLine 的执行脚本，接收 stdin 的 JSON，额外再去读本地的 transcript 文件（JSONL 格式，记录了工具调用、子 Agent 活动和 Todo 变更），把两部分数据拼在一起，格式化成带颜色的多行状态栏输出。

因此，Claude HUD 显示的上下文百分比、用量余量这些核心指标都是 Claude Code 自己算出来的，不是插件估算的，数据来源可靠。工具活动、Agent 状态这些则来自 transcript 日志，同样基于真实数据。整个链路不消耗 API Token，不需要 tmux，不需要额外窗口，任何终端都能用。

灵活配置指南

如果想调整 HUD 显示的内容，运行 /claude-hud:configure。它会提供三种预设方案，也可以逐项开关各个元素，配置过程中支持预览效果。

预设	显示内容
Full	全部开启——工具、Agent、Todo、Git、用量、时长
Essential	活动信息 + Git 状态，简洁不啰嗦
Minimal	只显示模型名称和上下文进度条

高级手动配置

高级用户可以直接编辑 ~/.claude/plugins/claude-hud/config.json。以下是一个推荐的完整配置示例：

{  
  "language": "zh",  
  "lineLayout": "expanded",  
  "pathLevels": 2,  
  "elementOrder": ["project", "tools", "context", "usage", "agents", "todos"],  
  "gitStatus": {  
    "enabled": true,  
    "showDirty": true,  
    "showAheadBehind": true,  
    "showFileStats": true  
  },  
  "display": {  
    "showTools": true,  
    "showAgents": true,  
    "showTodos": true,  
    "showDuration": true  
  }  
}

常用配置参数详解

配置项	类型	默认值	说明
`language`	`en`	`zh` / `en`	界面语言，设为 `zh` 可启用中文标签
`lineLayout`	`expanded`	`compact` / `expanded`	布局模式：多行展开或单行紧凑
`pathLevels`	1-3	1	项目路径显示的目录层数
`display.showTools`	boolean	false	显示工具活动行
`display.showAgents`	boolean	false	显示 Agent 状态行
`display.showTodos`	boolean	false	显示 Todo 进度行
`display.showCost`	boolean	false	显示会话费用
`display.showDuration`	boolean	false	显示会话时长
`display.showMemoryUsage`	boolean	false	显示系统内存使用
`display.showClaudeCodeVersion`	boolean	false	显示 Claude Code 版本号

Git 相关信息配置

Git 状态可显示以下细节：

配置项	说明	效果示例
`showDirty`	显示未提交修改标记	`git:(main)` 中的 ``
`showAheadBehind`	显示与远程分支的差异	`git:(main ↑2 ↓1)`
`showFileStats`	显示文件变更统计	`git:(main* !3 +1 ?2)`

文件统计中：!= 已修改，+= 已暂存，✘= 已删除，?= 未跟踪。数量为 0 的项会自动隐藏。

自定义配色方案

所有颜色都可以自定义，支持颜色名称（red、green、cyan、yellow、dim 等）、256 色编号（0-255）或十六进制值（#rrggbb）。

实时用量监控

用量显示是 Claude HUD 默认启用的核心功能。它直接读取 Claude Code 推送的订阅额度数据（rate_limits），告诉你当前 5 小时滚动窗口内用了多少、还剩多少。当 7 天累计用量超过 80% 时，还会额外显示 7 天的消耗百分比，提醒你注意使用节奏。

查看效果类似这样：

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

不过，这个功能并非对所有用户可见。它只对订阅账户生效——只有通过 Claude 订阅账户登录的用户才能看到。如果你用的是 API Key 接入（按 Token 付费，没有速率限制的概念），状态栏就不会有用量信息。通过 AWS Bedrock 等云厂商路由的用户同理——用量在云厂商侧管理，Claude Code 拿不到相关数据，所以 HUD 会直接隐藏这一行，而不是显示一个误导性的数字。

如果你发现用量信息始终不出现，最可能的原因是 Claude Code 版本或当前订阅层级尚未提供 rate_limits 数据。可以在 config.json 里确认 display.showUsage 没有被设为 false，如果仍无效，就等 Claude Code 后续更新。

多种显示效果预览

不同的配置会展示完全不同的效果：

默认 2 行模式：

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

开启全部扩展信息后：

[Opus] │ apps/my-project git:(main ↑2 !3 +1)  
Context █████░░░░░ 45% (45k/200k) │ Usage ██░░░░░░░░ 25% (1h 30m / 5h) | ⏱️ 12m  
◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2  
◐ explore [haiku]: Finding auth code (2m 15s)  
▸ Fix authentication bug (2/5)

路径层级对比：

层级	效果
1 层（默认）	`[Opus] │ my-project git:(main)`
2 层	`[Opus] │ apps/my-project git:(main)`
3 层	`[Opus] │ dev/apps/my-project git:(main)`

总结与建议

Claude HUD 真正解决了一个非常实际的痛点：让你不必时刻紧盯屏幕，也能完全掌控 Claude Code 的运行状态。

上下文管理：实时查看上下文使用率，在回复质量下降前及时 /compact
用量控制：直观地看到用量消耗，避免在关键时刻被限流
任务追踪：清楚看到 Agent 在做什么、任务完成了多少，不再“两眼一抹黑”

安装只要三条命令，配置随你调整，对性能的影响几乎感觉不到。许多开发者现在每次打开 Claude Code 第一眼就是看这个状态栏，强烈推荐你也立即安装体验。