Claude HUD 如何给Claude Code装上实时状态栏插件

前言

用 Claude Code 跑长任务时，上下文余量、subagent 状态、todo 进度这些东西，常常对用户不可见。工作流因此频繁中断——说白了，就是"盲飞"。

这里要聊的 Claude HUD 是一款 statusline 插件（GitHub 26k Star，MIT 协议），它通过 Claude Code 原生 statusline API + transcript JSONL 解析双数据源，在输入框下方常驻渲染上下文用量、工具活动、agent 状态、todo 进度等状态信息。

关键技术点包括：零运行时依赖、十余个 display 显示开关、完整 colors 颜色体系、三预设即用、简繁中文原生支持。适用于重度 Claude Code 用户，尤其依赖 subagent 并行与长上下文任务的开发者。

Claude HUD 给 Claude Code 装上实时状态栏插件，告别上下文盲区

想象一下这个场景：你正在用 Claude Code 改一个跨文件的 bug，它已经连续跑了 20 分钟。你不知道上下文还剩多少、不知道 subagent 在哪个目录里翻代码、不知道那 5 个 todo 完成了几个——直到上下文突然耗尽、任务被打断，你才意识到自己一直在"盲飞"。

Claude HUD 就是为这种盲飞时刻准备的：它在输入框下方常驻一行状态，把上下文用量、工具活动、agent 状态、todo 进度实时摊在你眼前。

一、Claude Code 的"信息盲区"：从看不见到看得见

把 Claude Code 用得越久，你就越会感受到一种隐性的"信息税"——它的能力很强，但过程中的关键状态对你不可见。这种盲区具体表现为三类。

Claude Code 的上下文窗口动辄 200K 甚至更大，但你看不到当前会话已经吃了多少、还剩多少。等到它突然提示上下文不足、要求你 /compact 或开新会话时，前面的工作流往往已经被打断。长任务尤其痛：你无法在"快满了"之前主动决策，只能被动响应。

当主 agent 派出 subagent 去探索代码库、跑测试或并行处理子任务时，这些子任务在你的视野里几乎是静默的——你不知道哪个 agent 还在跑、它停在哪一步、是否卡在某个目录里反复读同一个文件。任务越复杂，黑盒越深。

Claude Code 经常自己列 todo 清单并逐项执行，但这份清单藏在对话流里，你得往上翻才能看到还剩几项没做。20 分钟的连续执行中，进度感几乎是零。

这三类盲区叠加起来，构成了 README 在 “What You See” 一节中要解决的完整问题域：

（当前所在项目）、（上下文健康度）、（工具活动）、（agent 跟踪）、（todo 进度）。Claude HUD 把这五项一次性补齐。

二、Claude HUD 是什么：一行状态栏，一个 HUD

Claude HUD 是 Claude Code 的一个 statusline 插件，作者 Jarrod Watts。它在你输入框下方常驻渲染一两行（可扩展到更多行）状态信息，覆盖上下文用量、工具活动、agent 状态、todo 进度等维度。整套东西本地运行，不联网、不抓凭证，MIT 协议开源。

项目属性	数值
仓库	jarrodwatts/claude-hud
仓库地址	https://github.com/jarrodwatts/claude-hud
Stars	27k
License	MIT
主语言	Ja vaScript（TypeScript 编译）
运行时依赖	零（package.json 无 dependencies 字段，仅 devDependencies）

值得专门拎出来讲的是迭代速度，覆盖了 Bedrock/Vertex 成本显示、繁体中文支持、model-scoped weekly usage、安全加固、CJK 进度条对齐修复等。这不是一个"发完就躺平"的项目，而是处于高速活跃期。

装好之后，你看到的默认形态是这样（来自 README）：

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

第一行告诉你"用的是什么模型、在哪个项目、git 分支是否脏"；第二行告诉你"上下文吃了多少、订阅用量用了多少"。就这两行，已经把开篇那三个"不知道"补上了第一个。

三、它如何工作：原生 statusline API + transcript 解析

Claude HUD 的工作原理其实不复杂，核心就两条线。理解了它们，你就能解释它的各种行为。

Claude Code 暴露了一个 statusline 扩展点——插件注册一个可执行入口，Claude Code 会周期性地把当前会话状态以 JSON 形式通过 stdin 喂给这个入口，插件处理后把渲染好的字符串写回 stdout，Claude Code 再把它绘制到输入框下方。这意味着 Claude HUD 不需要 tmux、不需要单独窗口、不需要你切屏，只要能跑 Claude Code 的终端就能用。

stdin 里的 JSON 只覆盖一部分信息（模型名、上下文用量、transcript 路径等），更动态的"工具调用、agent 状态、todo 进度"来自 Claude Code 同时维护的 transcript JSONL 文件。Claude HUD 在拿到 transcript_path 后，会去解析这份 JSONL，提取出最近一次的 tool_use、subagent 调用、TodoWrite 等事件。数据流因此是这样的：

Claude Code ──stdin JSON──> claude-hud ──stdout──> 终端
                                 │
                                 └──解析 transcript JSONL──> tools/agents/todos

源码层面，src/ 目录按职责切得很细：stdin.ts 负责读 stdin，transcript.ts 解析 transcript JSONL，context-cache.ts 缓存上下文状态，config.ts / config-reader.ts 管配置，再加上 cost.ts / effort.ts / git.ts / memory.ts / model-source.ts / speed-tracker.ts / auth.ts 等功能模块，以及 i18n/、render/、utils/ 三个子目录。入口是 dist/index.js（编译产物，源码 src/index.ts）。技术栈是 TypeScript + ESM + Node 18+，构建走 tsc。

执行模式上，package.json 里的 test:stdin 脚本给出了很直白的证据——它就是一条管道：

echo '{"model":{"display_name":"Opus"},"context_window":{"current_usage":{"input_tokens":45000},"context_window_size":200000},"transcript_path":"/tmp/test.jsonl"}' | node dist/index.js

你可以直接拿这条命令在本地验证执行模式：claude-hud 是"读一次 stdin、输出一次状态行后退出"的单次进程，由 Claude Code 周期性调用。所以 README 里那句 “Updates every ~300ms”，根据项目文档的描述，应当理解为 Claude Code 调用 statusline 的频率，而不是 claude-hud 内部跑了个 setInterval。

同理，README 宣称的 “Native token data from Claude Code (not estimated)” 与 “scales with Claude Code’s reported context window size, including newer 1M-context sessions”，根据项目文档，是指 token 数与窗口大小取自 Claude Code 经 stdin 报告的值，而非 claude-hud 本地估算——这两项经源码核实与实现一致：token 数与上下文窗口大小均取自 stdin 的 context_window 字段，仅在旧版 Claude Code 未提供原生百分比时才回退到本地估算。

四、上手实战：4 条命令装好，3 个预设即用

Claude HUD 的上手成本被压到了很低：4 条 slash 命令装完，1 个交互式配置选预设，重启即可见。

运行要求

• Claude Code

  v1.0.80+
• macOS / Linux：Node.js 18+ 或 Bun
• Windows：Node.js 18+

安装 4 步

在 Claude Code 会话里依次执行（命令来源：README “Install” 一节）：

/plugin marketplace add jarrodwatts/claude-hud
/plugin install claude-hud
/reload-plugins
/claude-hud:setup

/claude-hud:setup 会帮你把 statusline 配置写好。完成后

让新的 statusLine 配置生效，HUD 就会出现在输入框下方。

三个预设即用

装好后运行 /claude-hud:configure，在三个预设里选一个（定义来自 README）：

预设	内容	适合
Full	全部启用	重度用户、长任务、想看尽一切
Essential	活动行 + git，精简显示	日常开发，平衡信息量与噪音
Minimal	仅模型名 + 上下文条	极简主义者、小屏 / 旧终端

/claude-hud:configure 是引导式的，会带你过布局、语言、常见显示开关，

——不用反复改了再看、看了再改。

平台坑与解法

/tmp 在大多数 Linux 发行版上是 tmpfs，安装时可能遇到 EXDEV: cross-device link not permitted。这是 Claude Code 平台限制（issue #14799），不是 claude-hud 的 bug。解法是把临时目录指到一个真实文件系统上：

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

把这条放进你的 shell 启动脚本或别名里，之后正常使用即可。

如果 /claude-hud:setup 提示找不到 Node，说明你的 Windows 上还没装 Node.js。装一份 LTS 就行：

winget install OpenJS.NodeJS.LTS

装完

（关掉当前终端、重开），让 PATH 生效，然后重跑 /claude-hud:setup。

手动配置入口

如果引导式配置不够用，各类高级选项都在配置文件里：

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

直接编辑这个 JSON 就能调 colors.*、pathLevels、maxWidth、各类阈值、display.timeFormat、display.promptCacheTtlSeconds 等细粒度参数。改完保存，下一次 statusline 刷新即生效。

五、亮点与配置：从默认 2 行到深度定制

默认 2 行只是起点。Claude HUD 真正的差异化在于配置深度——你能精确控制每一行显示什么、用什么颜色、中文还是英文。

可选显示行

通过 /claude-hud:configure 打开后，默认隐藏的三行会被启用（示例来自 README）：

◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2        ← Tools activity
◐ explore [haiku]: Finding auth code (2m 15s)    ← Agent status
▸ Fix authentication bug (2/5)                   ← Todo progress

这三行恰好分别对应开篇的三个"不知道"：工具在干什么、subagent 在哪、todo 进度几成。◐ 表示进行中、✓ 表示完成、▸ 表示当前 todo 项。

display.* 显示开关

显示维度被拆成了十余个独立开关，按需打开关闭（清单来自 README “Configuration”）：

• showTools / showSkills / showMcp：工具、技能、MCP 调用活动
• showAgents：subagent 状态
• showTodos：todo 进度
• showCost：成本（含 Bedrock/Vertex）
• showDuration / showSpeed：会话时长、输出速度
• showMemoryUsage：内存占用
• showPromptCache：prompt cache 命中
• showAuth / showCompactions / showEffortLevel / showClaudeCodeVersion：认证方式、压缩次数、推理努力等级、Claude Code 版本

这套开关的颗粒度足以让重度用户拼出自己舒适的信息密度，也让 Essential / Minimal 预设能精确地"少显示"。

colors.* 颜色体系

颜色不是写死的。colors.* 下有 context、usage、warning、critical、model、project、git、gitBranch、label、custom 等键，每个都支持三种写法（来自 README）：

• 颜色名（如 red）
• 256 色编号（如 196）
• hex（如 #ff5555）

你完全可以把上下文条调成跟终端主题一致的颜色，或者在 critical 阈值时用一个特别刺眼的红色提醒自己。

布局、路径、语言

• lineLayout：expanded（多行）或 compact（单行）。单行适合窄终端，多行适合看全信息。
• pathLevels：1-3，控制项目路径显示几层目录。
• language：en / zh / zh-Hans / zh-Hant / zh-TW。zh 是 zh-Hans 的别名，zh-TW 映射到 zh-Hant。简繁中文都原生支持，对中文开发者很友好。

临时禁用

调试时你想看原始 Claude Code 界面，不必卸载插件，设一个环境变量即可：

CLAUDE_HUD_DISABLE=1 claude

这一次会话不带 HUD 启动，下次正常启动自动恢复。

六、边界与注意事项：哪里能用，哪里要小心

Claude HUD 不是银弹，它有几条明确的边界，用之前心里有数才能避开坑。

前面提到的 Linux tmpfs EXDEV 和 Windows 找不到 Node 是两个常见的安装期问题，按第四节的解法处理即可。除此之外，macOS / Linux 用 Node 18+ 或 Bun 都行，Windows 只认 Node 18+（不支持 Bun），这是 README 明确写的运行要求。

Context 条旁边的 Usage 条不是人人都能看到，它依赖 Claude Code 在 stdin 里提供 subscriber rate_limits：

• API-key 用户不可用
  ：按 token 计费没有 rate limits，Claude Code 不会提供这个字段，Usage 条自然也不出现。

• Bedrock 用户
  ：会显示 Bedrock 标签但

  隐藏用量限制
  ，因为额度在 AWS 侧管理。

• Claude Code 可能延迟提供
  ：根据项目文档，Claude Code 有时会在首条响应之后才把 rate_limits 喂进 stdin，所以会话刚开始那几秒 Usage 条可能是空的，这不是 bug。
• 想补全或覆盖官方用量数据，可以配置 externalUsagePath 指向一个本地用量快照文件作为补充或回退。

Claude HUD 的安全姿态是"本地、最小、可控"：

• 本地运行 by design：不发起网络请求、不抓取凭证、不调用未公开的 Claude API。读取范围严格限定在 stdin 的 statusline JSON、Claude Code 提供的 transcript 路径、~/.claude 下选定的配置文件、当前工作区的 git 元数据。
• 缓存文件写在 ~/.claude/plugins/claude-hud，POSIX 下用私有权限，不会被其他用户读到。
• --extra-cmd 是高危选项：默认禁用，必须设环境变量 CLAUDE_HUD_ALLOW_EXTRA_CMD=1（或 true / yes / on）才会启用。README 明确警告：这个选项等同任意代码执行，切勿使用不可信来源的命令。如果你不知道自己在干什么，就别碰它。

总结

回到开篇的"盲飞"——Claude HUD 把它变成了一种可选状态，而不是默认状态。它的价值是四件事的乘积：

1. 原生 statusline API 的零侵入
   ：不抢窗口、不抢 tmux、不改你的工作流，绝大多数终端都能用。

2. 零运行时依赖的轻量
   ：package.json 没有 dependencies，装上不会拖进一堆供应链包袱。

3. 配置深度的可塑性
   ：十余个 display 开关、完整 colors 体系、布局/路径/语言全可调，从 Minimal 到 Full 覆盖大多数人的信息偏好。

4. 高速迭代的项目健康度
   ：5 天 5 个版本，issue 响应快，CJK、Bedrock、繁体中文这些边缘场景都在被照顾。

它尤其适合重度 Claude Code 用户——尤其依赖 subagent 并行、经常跑长上下文任务、需要主动管理 context window 的人。

对偶尔用一下的轻量用户，默认 Minimal 预设也足够了。