Claude HUD：把 Claude Code 的上下文占用、工具调用和子代理状态钉在输入框下方

它解决的是会话里的信息黑洞

Claude Code 在终端里运行时，你看到的只是输入框和输出流。上下文窗口还剩多少，当前调用的是哪个工具，子代理在做什么，待办列表推进到哪一步，这些信息默认都不在视野内。Claude HUD 把这几项压缩成两行或多行状态栏，固定在输入框下方。它的目标用户是那些跑长任务、开多个子代理、或者频繁接近上下文上限的人。对短会话和简单提问，这个插件基本没有存在感。

数据来源：statusline API 加 transcript 解析

Claude HUD 不估算 token，它直接读 Claude Code 上报的原生 token 数据。上下文条和用量条都来自这个通道，所以它能适配 Claude Code 报告的窗口大小，包括新的 1M 上下文会话。工具活动、子代理状态和待办进度则来自另一条路：解析 transcript JSONL 文件。README 里的数据流示意写得很清楚：Claude Code 通过 stdin 把 JSON 喂给 claude-hud，插件处理后从 stdout 输出到终端，同时从 transcript JSONL 里提取工具和代理信息。每次交互后它会重绘，包括新助手消息、`/compact`、权限变化和 vim 模式切换，重绘有 300ms 防抖。这个防抖是必要的，否则每次工具调用都会触发整行刷新，终端会闪得没法看。

安装：三条命令，但有两个平台坑

安装路径很直接。在 Claude Code 会话里执行 `/plugin marketplace add jarrodwatts/claude-hud`，然后 `/plugin install claude-hud`，最后 `/reload-plugins`。不想进会话的话，也可以用 CLI 命令 `claude plugin marketplace add jarrodwatts/claude-hud` 和 `claude plugin install claude-hud@claude-hud`。装完还要跑一次 `/claude-hud:setup` 来配置 statusline。README 明确警告了两个坑：Linux 老版本可能因为 /tmp 是独立文件系统而报 `EXDEV: cross-device link not permitted`，解决办法是先升级 Claude Code，或者设置 `TMPDIR=~/.cache/tmp` 再启动。Windows 上如果 setup 提示找不到 JavaScript 运行时，需要先装 Node.js LTS，命令是 `winget install OpenJS.NodeJS.LTS`。这两个坑都不是插件本身的 bug，但足以让新用户卡住。

配置层级：预设、向导和手改文件

配置分三层。第一层是 `/claude-hud:configure` 引导流程，它提供三个预设：Full 显示所有内容，Essential 只留活动行和 git 状态，Minimal 只显示模型名和上下文条。选完预设后还能单独开关每个元素。第二层是直接编辑 `~/.claude/plugins/claude-hud/config.json`，可以设置 `colors.*`、`pathLevels`、`maxWidth`、阈值覆盖、`display.timeFormat`、`display.hourCycle` 和 `display.promptCacheTtlSeconds`。第三层针对多配置目录的场景：如果你用 `CLAUDE_CONFIG_DIR` 并符号链接共享 plugins 目录，那么共享的 config.json 是同一份文件，这时可以把每目录的差异写进 `$CLAUDE_CONFIG_DIR/claude-hud.json`，它只覆盖你指定的键。这个设计避免了多项目配置互相污染，但代价是你要理解两层配置的合并规则。

显示内容与语言选项的取舍

默认两行布局第一行显示模型名、可识别的提供商标签（比如 Bedrock、Vertex、MiniMax）、项目路径和 git 分支。第二行是上下文条和用量条，上下文条用绿黄红三色渐变表示占用比例。可选行包括工具活动、子代理状态和待办进度。路径显示支持 1 到 3 级目录或完整路径，`pathLevels` 默认是 1。语言方面，英文是默认，简体中文和繁体中文是显式 opt-in，通过 `zh` 或 `zh-Hans` 映射到简体，`zh-TW` 映射到繁体。引导配置会写入规范的 `zh-Hans` 或 `zh-Hant`。这个设计合理，因为状态栏空间有限，多语言标签会挤占宽度。

已知限制：宽度检测、重绘频率和插件生态依赖

插件依赖终端宽度检测来排版，如果检测失败，`maxWidth` 可以作为回退值，但默认是 `null`，意味着失败时不设限。`forceMaxWidth` 可以强制使用设定值，但只在 `maxWidth` 有值时生效。另一个限制是重绘机制：它只在交互后重绘，不是实时流式更新，工具调用之间的状态变化可能有延迟。更根本的限制是它完全依赖 Claude Code 的插件系统和 statusline API，如果上游 API 变动，插件需要跟进适配。另外，解析 transcript JSONL 意味着它只能看到 Claude Code 记录的内容，如果 transcript 格式变化，解析逻辑就得改。

替代方案：原生 statusline 脚本与 tmux 侧边栏

Claude Code 本身支持自定义 statusline，你可以写一个脚本从环境变量或 stdin 读取数据，自己渲染显示。这种做法更轻量，不依赖插件市场，但你需要自己处理 JSON 解析、防抖和宽度适配，而且拿不到 Claude HUD 已经做好的工具活动解析和子代理跟踪。另一个思路是用 tmux 或 screen 的侧边栏跑一个单独的监控进程，实时 tail transcript 文件。这种方式能显示更多历史信息，但需要额外窗口管理，而且无法利用 Claude Code 的 statusline API 拿原生 token 数据。Claude HUD 选择的是折中：用官方 API 保证数据准确，用 transcript 解析补充细节，代价是插件生态的耦合。

维护与许可证：MIT 下的活跃更新

仓库的最近提交显示 v0.8.0 发布于 2026-08-18，距离 v0.7.2 仅一天，说明维护节奏很快。MIT 许可证意味着你可以自由修改和分发，但没有任何担保。升级成本方面，插件通过 marketplace 安装，更新应该走 Claude Code 的插件更新机制，具体命令 README 没写，需要查 Claude Code 文档。配置文件的兼容性是个注意点：如果升级改变了 config.json 的结构，手动设置的 `colors.*` 或阈值覆盖可能失效。好在 README 提到引导配置会保留高级覆盖，说明作者考虑了这个问题。

编辑结论

Claude HUD 适合那些在长会话里经常被上下文耗尽打断、或者需要同时盯多个子代理的 Claude Code 重度用户。它把原本藏在 transcript JSONL 里的信息拉到眼前，省去反复猜测。不适合的场景包括：你只用单行终端、对多余视觉元素敏感，或者你的 Claude Code 版本过旧且无法升级，因为旧版本可能触发 EXDEV 安装错误或需要重启才能加载 statusLine。采用前先确认三件事：你的 Claude Code 版本能正常安装插件，`/claude-hud:setup` 能找到 JavaScript 运行时，以及你愿意接受它每 300ms 防抖重绘带来的轻微终端刷新。若这些条件满足，它就是一个低侵入、可配置的监控层。

官方来源

1. Official README
2. Project repository
3. Release notes