Claude Code HUD 插件实战：给你的 AI 编程工具装上仪表盘

痛点：写着写着，AI 突然开始犯傻#

你有没有遇到过这种场景：

用 Claude Code 写代码，一切正常。突然之间——

回答变得越来越短
之前说好的方案全忘了
逻辑开始混乱，甚至重复说同一件事

然后你看到终端里蹦出一行字：

1
context window is getting full

上下文窗口满了。 你只能关掉重来，之前聊的所有内容全部丢失。

最气人的是：在爆掉之前，你完全不知道上下文用了多少。 你得手动输入 /context 才能查，但谁写代码的时候会记得去查这个？

等你发现的时候，已经晚了。

解决方案：给 Claude Code 装个 HUD#

前两天我在 GitHub 上发现了一个叫 claude-hud 的插件，作者是 Jarrod Watts。

装上之后，终端底部会多出一个实时状态栏，像这样：

1
Context ████████░░ 72%  |  Usage ██░░░░░░░░ 25% (1h 30m / 5h)
2
◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2
3
◐ explore [haiku]: Finding auth code (2m 15s)
4
▸ Fix authentication bug (2/5)

一眼就能看到 5 个关键信息：

信息	说明	重要程度
当前模型	Opus / Sonnet / Haiku	⭐⭐
上下文窗口用量	进度条，绿→黄→红	⭐⭐⭐⭐⭐
订阅额度	5 小时滑动窗口用量	⭐⭐⭐⭐
工具活动	正在读文件/编辑/搜索	⭐⭐⭐
Agent 状态	子 Agent 名称 + 运行时间	⭐⭐⭐⭐

以前是盲开，现在心里有数。

安装：3 条命令，不到 1 分钟#

我最怕那种安装步骤写了两页纸的工具。这个不一样，3 条命令搞定：

1
# 第1步：添加插件市场
2
/plugin marketplace add jarrodwatts/claude-hud
3

4
# 第2步：安装插件
5
/plugin install claude-hud
6

7
# 第3步：配置状态栏
8
/claude-hud:setup

装完立刻生效，不用重启。

⚠️ Linux 用户注意：如果安装报错 EXDEV: cross-device link not permitted，先跑这个：
Terminal window
1
mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude
然后在这个会话里重新安装。这是 Claude Code 平台的已知问题，不是插件的锅。

核心功能拆解#

1. 上下文健康度（最有用的功能）#

1
Context █████░░░░░ 45%

这个进度条会变色：

颜色	阈值	含义	建议操作
🟢 绿色	0-60%	安全，随便用	继续工作
🟡 黄色	60-85%	注意了，AI 开始控制输出	考虑 `/compact`
🔴 红色	85%+	快爆了，赶紧处理	`/compact` 或开新会话

到了 85% 以上，它还会自动显示 token 明细，告诉你哪部分占用最多。

这个功能值回票价。 以前上下文爆掉都是事后才知道，现在随时能看到，心里踏实多了。

2. 订阅额度监控（Pro/Max 用户福音）#

1
Usage ██░░░░░░░░ 25% (1h 30m / 5h)

如果你是 Claude Pro 或 Max 订阅用户，这个功能太实用了。

它会实时显示：

5 小时滑动窗口用了多少
还剩多少时间重置
7 天额度快到时提醒（默认 80% 阈值）

我之前经常用着用着突然被限速，完全不知道额度花到哪去了。现在一看进度条，心里有数，该省省该花花。

3. 工具活动追踪#

1
◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2

这行显示 AI 当前正在干什么——在读文件、在编辑代码、还是在搜索。

一开始我觉得这个功能可有可无。但用了之后发现，当 AI 卡住不动的时候，看一眼这行就知道它是在思考还是在跑工具，不用干等着瞎猜。

4. Agent 状态追踪#

1
◐ explore [haiku]: Finding auth code (2m 15s)

如果你用了子 Agent（比如 Task 工具派出去的探索 Agent），这行会显示：

Agent 名称和用的模型
正在干什么
已经跑了多久

我经常派 Agent 去搜代码，以前完全不知道它跑到哪了。现在一看，“哦，已经跑了 2 分钟了，还在找”，心里有底。

5. Todo 进度追踪#

1
▸ Fix authentication bug (2/5)

如果 AI 在用 TodoWrite 跟踪任务，这行会显示当前进度。比如 5 个任务完成了 2 个，一目了然。

配置：3 种预设，随你选#

装完之后，运行 /claude-hud:configure 可以自定义。它会引导你选一个预设：

预设	显示内容	适合人群
Minimal	上下文 + 用量	极简主义者
Essential（推荐）	上下文 + 用量 + 工具活动	大多数用户
Full	全部功能	信息狂

选完预设之后，还能单独开关每个功能。

我用的是 Essential，再手动开了工具追踪。Full 太满了，Minimal 又太少，Essential 刚刚好。

配置文件在 ~/.claude/plugins/claude-hud/config.json，也可以直接改 JSON。

技术实现：为什么它能做到#

我扒了一下源码，看看它是怎么实现的。

核心原理#

用的是 Claude Code 原生的 statusline API：

1
Claude Code → stdin JSON → claude-hud → stdout → 终端显示
2
           ↘ transcript JSONL（工具、Agent、Todo 数据）

简单说就是：

Claude Code 会通过 stdin 把当前状态（模型、token 用量等）传给插件
插件同时解析 transcript 文件，获取工具和 Agent 的活动信息
处理完之后输出到终端底部的状态栏

几个技术亮点#

亮点	说明
原生 Token 数据	不是估算的，直接从 Claude Code 获取，准确度很高
300ms 刷新	基本是实时的，不会有明显延迟
零运行时依赖	纯 TypeScript 实现，只有 devDependencies
管道式设计	读 stdin → 解析 transcript → 读配置 → 获取 Git 状态 → 获取用量 → 渲染输出

入口函数 src/index.ts 很简洁，每个模块职责单一，13 个源文件，没有花里胡哨的东西。

这种设计我很欣赏：不搞额外窗口，不依赖 tmux，就用原生 API，简单直接。

坑：老金说过的 + 我自己踩的#

用了两天，总结一下遇到的问题：

1. API 用户看不到 Usage#

如果你是用 API Key 而不是订阅账号登录的，Usage 那行不会显示。因为 API 是按量计费，没有速率限制的概念。

2. 工具/Agent/Todo 默认是关的#

装完之后你可能觉得”就这？只有两行？“别急，工具追踪、Agent 追踪、Todo 追踪默认都是关闭的，需要手动开启。跑一下 /claude-hud:configure 就能开。

3. Windows 路径问题#

在 Windows 上用，偶尔 Git 状态显示不出来。重新跑一下 setup 就好了，不是大问题。

4. 和我自己的 OpenClaw 环境对比#

我服务器上的 OpenClaw 其实也有类似的能力——/status 命令可以查看模型、上下文用量、会话信息。但 OpenClaw 是在 Web 面板里看的，不是终端内嵌的。两者互补，不冲突。

能力	claude-hud	OpenClaw /status
上下文用量	✅ 实时进度条	✅ 数字显示
订阅额度	✅ 滑动窗口	❌ OpenClaw 用百炼 API，无此概念
工具活动	✅ 实时	❌
Agent 状态	✅ 实时	✅ 通过 sessions_list 查看
终端内嵌	✅	❌ Web 面板

谁该装这个？#

强烈推荐装的#

Claude Code 重度用户（每天用超过 2 小时的）
Pro/Max 订阅用户（需要监控额度的）
经常用子 Agent 的（需要追踪 Agent 状态的）

可以不装的#

偶尔用一下 Claude Code 的轻度用户
对终端界面有洁癖、一行多余信息都不想看的

我的建议：只要你每天用 Claude Code 超过 1 小时，这个插件就值得装。 光是上下文监控这一个功能，就能帮你避免很多”上下文爆掉重来”的痛苦。

总结#

claude-hud 解决的是一个很小但很痛的问题：让你看到 Claude Code 的运行状态。

3 条命令安装，零配置就能用，想定制也很方便。

用了两天，最大的感受就是——以前用 Claude Code 像开没有仪表盘的车，现在终于知道油还剩多少了。

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

音乐

音乐