Claude HUD 三步安装与快速配置：给输入框下方加一块实时状态看板-育师

Claude HUD 三步安装与快速配置：给输入框下方加一块实时状态看板

【免费下载链接】claude-hudA Claude Code plugin that shows what's happening - context usage, active tools, running agents, and todo progress项目地址: https://gitcode.com/GitHub_Trending/cl/claude-hud

Claude HUD 是一款常驻在 Claude Code 输入框下方的插件，上下文用量、活跃工具、运行中的子代理、待办进度和订阅配额，一屏尽览。本文带你按"装好 → 选预设 → 手动调参 → 排坑"的顺序走一遍：三条命令装完，向导里选预设，再用几个关键参数调成自己的样子。

一眼看清会话里正在发生什么

用 Claude Code 跑长任务时，有三个问题你没法轻松回答：上下文窗口还剩多少？Claude 此刻在读、改哪些文件？多步任务走到第几点了、哪些子代理还在跑？没有实时显示，你只能靠往上翻输出猜，或者主动追问一句——而追问本身又消耗上下文。

Claude HUD 挂在 Claude Code 原生的 statusline 机制上，不占额外窗口、不依赖 tmux，在任何终端里持续绘制一块"仪表盘"：

HUD 上的信息	帮你省掉的麻烦
模型、项目路径、Git 分支	不用记当前跑在哪个项目、哪个分支上（未提交改动带`*`标记）
上下文进度条	不用猜上下文什么时候会撑满，绿→黄→红一目了然
工具活动行	实时看到 Claude 正在读、编辑、搜索哪些文件
代理状态行	知道哪个子代理在跑、在做什么、跑了多久
待办进度	任务完成度`2/5`随时可见
订阅使用率	5 小时窗口与 7 天窗口的配额消耗和重置时间

数据来自 Claude Code 的原生上报而非估算，自动适配 1M 上下文窗口，每次交互后带 300ms 防抖重绘。

三条命令装好 Claude HUD 并让它显示出来

先确认运行环境：Claude Code v1.0.80+；macOS/Linux 需要 Node.js 18+ 或 Bun，Windows 需要 Node.js 18+。

在 Claude Code 会话里依次执行：

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

重载插件，然后跑初始化向导：

/reload-plugins /claude-hud:setup

setup 完成后随便发一条消息，HUD 就会出现在输入框下方——当前版本无需重启（旧版 Claude Code 需要重启才能加载 statusLine 变更）。默认你会看到两行：

[Opus] │ my-project git:(main*) 上下文 █████░░░░░ 45% │ 使用率 ██░░░░░░░░ 25%（1小时30分 / 5小时）

注意两点：

Linux 上报EXDEV: cross-device link not permitted，多出现在旧版 Claude Code 的 /tmp 文件系统上，优先升级 Claude Code；
Windows 上 setup 提示找不到 JavaScript 运行时，先装 Node.js LTS，重开终端再跑/claude-hud:setup。

setup 的完整分支逻辑（各平台命令差异、备份机制）见 commands/setup.md。

用 configure 向导选预设：布局、语言、元素开关一次配完

装好后的 Claude HUD 只有默认两行，工具、代理、待办这些活动行默认全部隐藏。运行：

/claude-hud:configure

向导按固定顺序问你 6 个问题：选布局（expanded 多行 / compact 单行 / 单行带分隔符）→ 选预设 → 选标签语言（支持简体中文zh-Hans、繁体中文zh-Hant）→ 关掉预设里多余的元素 → 打开预设里没有的元素 → 可选的自定义文案。保存前会给一次真实 HUD 预览，配错了当场就能看出来。

三个预设，按信息密度从高到低：

预设	包含内容	适合谁
Full	全开：工具、代理、待办、Git、使用率、时长	复杂项目、多任务并行
Essential	活动行 + Git 状态，信息从简	日常编码
Minimal	只有模型名和上下文进度条	小终端、极简偏好

选完预设还可以逐个元素微调。下面就是 Full 预设把活动行全部打开后的 Claude HUD：

手动配置：一个配置文件与最常用的 5 个参数

向导覆盖常用开关，颜色、阈值、元素顺序这类进阶项则要直接编辑配置文件：

~/.claude/plugins/claude-hud/config.json

最常动到的 5 个参数（最小可运行示例）：

{ "language": "zh-Hans", "lineLayout": "expanded", "pathLevels": 2, "elementOrder": ["project", "tools", "context", "usage", "agents", "todos"], "display": { "showTools": true, "showAgents": true, "showTodos": true } }

language：标签语言，zh-Hans即简体中文；
lineLayout：expanded多行，compact单行；
pathLevels：项目路径显示几级目录，取 1–3 或full；
elementOrder：展开模式下各元素的排列顺序，省略的元素直接隐藏；
display.show*：控制工具/代理/待办三行的显示开关，默认都是false。

注意：JSON 语法错误会静默回退到默认值——"改了没反应"时先查语法。完整的几十个参数（colors.*、gitStatus.*、使用率阈值、时间格式等）见 README.zh.md 的选项表。

三个真实场景：按你的工作方式挑组合

Claude HUD 没有万能配置，同一批开关，组合方式不同，服务的工作就不一样。挑三种最常见的干活方式：

场景一：多代理长任务，想知道"它现在在干什么"。开showTools加showAgents，HUD 会实时滚动工具与子代理：◐ Edit: auth.ts | ✓ Read ×3、◐ explore [haiku]: 查找认证代码（2分15秒）。再开showTodos，任务进度以2/5呈现，不用回头翻对话。

场景二：订阅用户盯配额，怕关键时候撞线。使用率默认开启（前提是 Claude Code 上报了 rate_limits 数据；API 密钥用户看不到）。把"已用百分比"换成"剩余配额"，并压缩成短格式：

{ "display": { "usageValue": "remaining", "usageCompact": true } }

7 天窗口默认在使用率达到 80% 时才显示；想更早收到预警，把display.sevenDayThreshold调低。

场景三：小终端，只想占一行。lineLayout改成compact，配pathLevels: 1，Claude HUD 会把全部内容压进单行——信息够用，不占纵向空间。

自检清单：症状对得上，就照这一列修

下面是 Claude HUD 常见问题的自检清单，按症状找原因：

症状	可能原因	解决办法
setup 后 HUD 不显示	状态栏只在下一次交互后重绘；旧版 Claude Code 需重启	先随便发一条消息；仍不出现就重启 Claude Code
改了配置不生效	JSON 语法错误静默回退默认值；或取值越界	修正语法；`pathLevels`只认 1/2/3/`full`，`lineLayout`只认`expanded`/`compact`
git 分支不见了	不在仓库目录，或`gitStatus.enabled`被设为`false`	进入仓库目录，检查配置
工具/代理/待办行没有	默认隐藏，或当前没有对应活动	`showTools`/`showAgents`/`showTodos`设为`true`，并等 Claude 真正触发对应行为
倒计时在消息之间不走	Claude Code 只在交互后重跑状态栏	在`~/.claude/settings.json`的`statusLine`对象里加`"refreshInterval": 5`
想临时藏起 HUD	—	`CLAUDE_HUD_DISABLE=1 claude`仅本次会话禁用，不动配置