一个开源插件 Claude HUD，把上下文余量、工具调用、子代理、Todo 进度做成常驻状态栏，就摆在你输入框下面。
先说一个我自己的日常
用 Claude Code 干活的时候，我心里经常悬着几个问题：
- 上下文窗口（可以理解成 AI 这一次会话的"内存"，装满了它就开始忘事）还剩多少？会不会干着干着突然爆掉，前面聊的东西全忘了？
- 它现在到底在干嘛？是卡住了，还是在后台吭哧吭哧读文件？
- 派出去的子代理（主 AI 派去干杂活的"小弟"）跑了多久了？
- 任务清单做到第几条了？
这些问题以前怎么解决？翻日志、敲/context、或者干等它自己提示。就像开车不看油表，全凭感觉估计还剩多少油——开短途没事，跑长途迟早趴窝。
前阵子我刷 GitHub 的时候看到一个项目，叫Claude HUD，作者 jarrodwatts。它干的事情很简单：把上面这些信息做成一条（或几条）常驻状态栏，直接放在 Claude Code 输入框下面，不弹窗、不抢焦点、不用另开终端，抬头就能看见。
我试了一个星期，回不去了。这篇文章就讲讲它是怎么回事。
Claude HUD 是个啥？
一句话：给 Claude Code 终端装一个实时仪表盘。
它是一个开源插件（MIT 协议，TypeScript 写的，目前在 GitHub 上大约 3.7k Star、166 Fork，还在持续更新）。装好之后，你的终端输入框下方会多出几行状态栏，实时显示：
| 你能看到 | 举个例子 | 为啥有用 |
|---|---|---|
| 项目路径 | my-project（可调 1~3 层深度） | 同时开几个项目时，确认自己在哪个仓库、哪个分支 |
| 上下文健康度 | █████░░░░░ 45%，绿→黄→红 | 快满之前心里有数，提前压缩或开新会话，而不是等着"失忆" |
| 用量限制 | ██░░░░░░░░ 25% (1h 30m / 5h) | Pro/Max/Team 订阅用户看限流余量，避免干到一半被限速 |
| 工具活动 | ◐ Edit: auth.ts │ ✓ Read ×3 │ ✓ Grep ×2 | 看 AI 正在读哪个文件、搜索了几次，卡没卡住一目了然 |
| 子代理状态 | ◐ explore [haiku]: Finding auth code (2m 15s) | 小弟在干啥、跑了多久、用的什么模型 |
| Todo 进度 | ▸ Fix authentication bug (2/5) | 任务清单完成到第几条，方便和 AI 对进度 |
| Git 信息 | 分支、未提交标记*、超前落后↑2 ↓1 | 减少在错误分支上瞎操作的翻车 |
默认情况下显示两行：第一行是模型名、项目路径和 Git 分支，第二行是上下文条和用量条。其他行（工具、Agent、Todo）默认关着，要自己在配置里打开——这一点后面细说。
三分钟装好
前提：Claude Code v1.0.80 以上，macOS/Linux 需要 Node.js 18+ 或 Bun（Windows 装 Node.js 18+）。
直接在 Claude Code 会话里敲三条命令：
# 第 1 步：添加插件市场 /plugin marketplace add jarrodwatts/claude-hud # 第 2 步：安装插件 /plugin install claude-hud # 第 3 步：配置状态栏（首次会引导你选预设和选项） /claude-hud:setup装完输入下一条消息时 HUD 就出现了，不用重启。如果你的 Claude Code 版本比较老没反应，完全退出再claude启动一次就行。
Linux 用户注意一个坑：老版本 Claude Code 在/tmp是独立文件系统的机器上安装会报EXDEV: cross-device link not permitted（跨设备硬链接不允许，属于 Claude Code 的老 bug，新版本已修）。暂时升不了级的话，启动前换个临时目录：
mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude然后在同一个会话里执行第 2、3 步。
装完想改设置，随时运行/claude-hud:configure进引导式配置，或者直接编辑~/.claude/plugins/claude-hud/config.json。
它是怎么拿到这些数据的？
这是我翻了下 README 和源码结构之后觉得最巧妙的地方：它没有自己去估 token，也没有黑魔法。
数据来源有两路：
- Claude Code 的原生 statusline API（statusline 就是输入框下方那一行状态文字，Claude Code 允许插件接管它）。这一路拿到的是真实 token 数据，不是估算——很多人自己写的监控脚本靠字符数除以系数去猜 token，误差不小，HUD 直接用的官方数字。
- 会话的 transcript JSONL（JSONL 就是一行一条 JSON 的日志文件，相当于会话的"行车记录仪"）。工具调用、子代理、Todo 这些信息都是从这里面解析出来的。
整条数据链长这样：
Claude Code → stdin JSON → claude-hud → stdout → 显示在终端 ↘ transcript JSONL（工具、Agent、Todo）刷新方面，Claude Code 每次交互（新消息、/compact压缩完成、权限模式变化等）之后都会重跑一次状态栏，HUD 在这里做了 300ms 的防抖（意思是不管多密集的更新，最多每 300ms 渲染一次，既跟手又不闪屏）。
还有一个细节：由于 Claude Code 在你没发消息的空档不会刷新状态栏，"会话时长""用量倒计时"这种时间类信息会僵住。想让它持续走，可以在~/.claude/settings.json的 statusLine 里加个刷新间隔：
{ "statusLine": { "type": "command", "command": "...", "refreshInterval": 5 } }官方建议 5 秒就够，设 1 秒倒计时最丝滑但会更费一点资源。
能调到多细？
三种预设，覆盖大多数人的口味：
| 预设 | 显示内容 |
|---|---|
| Full | 全开：工具、Agent、Todo、Git、用量、时长 |
| Essential | 活动行 + Git，信息量适中（我用的就是这个） |
| Minimal | 只留模型名和上下文条 |
选完预设还能逐项微调。常用的配置项我列几个：
| 配置项 | 说明 |
|---|---|
lineLayout | expanded多行 /compact单行 |
pathLevels | 项目路径显示 1~3 层，或full全路径 |
display.showContextBar | 是否显示上下文进度条 |
display.contextValue | 显示百分比、token 数、剩余量或都要 |
display.showUsage | 是否显示订阅用量条（Pro/Max/Team） |
display.sevenDayThreshold | 7 天用量超过这个百分比才显示（默认 80，设 0 常显） |
display.showTokenBreakdown | 上下文超 85% 时显示 token 细分 |
display.showTools/showAgents/showTodos | 工具行 / Agent 行 / Todo 行开关（默认关） |
gitStatus.showAheadBehind | 显示和远程的超前落后↑N ↓N |
colors.* | 各种颜色，支持色名、256 色号、十六进制 |
给一个我参考 README 改的配置示例，中文标签 + 开全活动行：
{ "language": "zh", "lineLayout": "expanded", "pathLevels": 2, "gitStatus": { "enabled": true, "showDirty": true, "showAheadBehind": true, "showFileStats": true }, "display": { "showTools": true, "showAgents": true, "showTodos": true, "showDuration": true } }顺便说一句，它支持简体和繁体中文标签，/claude-hud:configure里选语言就行，对中文用户挺友好。
适合谁装？不适合谁？
从我的使用体验和社区反馈看，这几类人装了提升明显：
- 重度 Claude Code 用户：长会话经常干到上下文见底的人，上下文条基本是刚需
- Pro/Max/Team 订阅用户：想直观看限流余量和 7 天占比，别干到一半被限速
- 喜欢观察 AI 行为的人：看子代理在干嘛、工具调用了几次，调试和学习都方便
- 多项目切换的人：路径 + Git 信息常驻，不容易搞错仓库和分支
不太适合的情况也说清楚：
- API Key 按量付费的用户看不到用量条（人家是按 token 计费，没有"限流"概念）
- 走AWS Bedrock / Vertex的会只显示提供商标签，用量由云厂商管
- 用量展示依赖 Claude Code 的订阅账号 OAuth 登录，API Key 登录看不到
和另外两种常见做法对比一下：
| 对比项 | Claude HUD | 什么都不装 / 翻日志 | 自己写脚本监控 |
|---|---|---|---|
| 可见性 | 常驻输入下方，实时 | 要切屏、敲命令 | 看实现 |
| 数据准确性 | 原生 statusline，真实 token | 无 | 多数靠估算 |
| 配置成本 | 预设 + 引导配置 | 无 | 自己维护 |
| 上手成本 | 三条命令 | 无 | 要对接 API |
几个我踩过或看到别人踩的坑
配置改了没反应？先检查 JSON 语法——无效配置会静默回退到默认值，不报错。pathLevels只能是 1、2、3 或full，lineLayout只能是expanded或compact。实在不行删掉配置文件重新跑/claude-hud:configure。
Git 信息不显示？确认当前目录在 Git 仓库里，且gitStatus.enabled没被设成false。
工具/Agent/Todo 行不出现？这几行默认是关的，要在配置里打开；而且它们只在有对应活动时才显示——没有子代理在跑，Agent 行自然不出现，不是坏了。
用量条不显示？按顺序检查：是不是用订阅账号（而不是 API Key）登录的；display.showUsage是不是被关了；当前会话是否至少有过一次模型响应（Claude Code 在首次响应前可能不带限流数据）。
想临时关掉 HUD？不用删配置，启动时加个环境变量：
CLAUDE_HUD_DISABLE=1 claude安全性方面我特意看了一眼：整个插件是纯本地的，不联网、不抓凭证、不调未公开接口，只读 statusline 输入、会话 transcript 和 Git 元数据。缓存文件也写在本地插件目录下，权限是私有的。
名词速查表
| 名词 | 一句话解释 |
|---|---|
| 上下文窗口 | AI 单次会话能"记住"的内容上限，类似手机运存，满了就开始忘 |
| token | AI 处理文字的最小单位，一个汉字约等于一个 token |
| statusline | Claude Code 输入框下方的那行状态文字，插件可以接管它 |
| 子代理（subagent） | 主 AI 派出去并行干活的辅助 AI，各用各的上下文 |
| transcript | 会话的流水账日志，AI 的每一步操作都记在上面 |
| JSONL | 一行一条 JSON 的日志格式 |
| tmux | 终端里的分屏工具，有些人拿它来盯多个窗口 |
| 限流（rate limit） | 订阅套餐的用量上限，类似手机流量，超了就降速 |
| 防抖（debounce） | 把密集的更新合并，固定间隔才执行一次 |
项目地址
- GitHub：jarrodwatts/claude-hud（MIT 协议，README 很完整，有中文文档）
- 问题反馈：GitHub Issues
如果你也天天用 Claude Code，又被"上下文还剩多少"这个问题折磨过，可以装上试试。装完要是觉得没用，卸载也就一条命令的事。
