Claude HUD

这是什么？适合谁？

Claude HUD（github.com/jarrodwatts/claude-hud，约 27.5k Stars，MIT）是一款 Claude Code 插件，官方一句话定位是「A Claude Code plugin that shows what’s happening — context usage, active tools, running agents, and todo progress」。它在 Claude Code 输入框下方常驻一条状态栏，实时显示项目路径、上下文窗口占用、模型用量/限速、正在读写的文件、运行中的子 Agent 以及 Todo 进度，让原本「黑盒」的 AI 编程过程变得透明。

相比同类工具，Claude HUD 的差异化在于零额外窗口、零 tmux：它直接使用 Claude Code 原生的 statusline API 渲染，在任何终端里都能工作，且 Token 数据来自 Claude Code 原生上报（而非估算）。横向对比：ccusage 是一个独立的 Web 用量看板，功能更偏账单统计但需要另开服务；claude-code-cost 之类脚本则侧重成本统计而非实时活动；而 Claude HUD 专注「会话内的实时状态」，与它们互补而非互斥。

适合谁：① 重度 Claude Code 用户，想随时知道上下文还剩多少、避免被动触发压缩（/compact）；② 需要追踪子 Agent（subagent）和 Todo 完成度的复杂任务用户；③ 在 Windows/macOS/Linux 终端里使用 Claude Code 的开发者。

使用前提：已安装并登录 Claude Code（需 Claude Pro/Max 订阅或 API），会使用 Claude Code 的 / 斜杠命令。

准备工作

1. 环境要求：Claude Code 可用的任意平台（macOS / Windows / Linux）与任意终端；Claude HUD 无独立依赖。
2. 运行时注意：Windows 上若 setup 提示「no JavaScript runtime was found」，需先装 Node.js LTS（见踩坑 2）；Linux 老版本 Claude Code 可能遇 EXDEV 错误（见踩坑 1）。
3. API/订阅来源：Claude HUD 免费（MIT），但需要 Claude Code 本身可用——Claude Pro $20/月、Max $100/月（订阅）或 Anthropic API Key。来源：anthropic.com/pricing。
4. 前置知识：会用 Claude Code 基本命令（/plugin、/reload-plugins 等斜杠命令）。
5. 替代方案：若想要跨会话的用量账单统计，用 ccusage；若想在网页里看成本，用 claude-code-cost；若只用 DeepSeek 生态，可看本站 awesome-deepseek-harness 里的 dsh-hud 类插件。

快速上手（5步）

在任意一个 Claude Code 会话里，依次执行以下命令：

第一步：添加插件市场

/plugin marketplace add jarrodwatts/claude-hud

预期结果：提示 marketplace 添加成功。

第二步：安装插件

/plugin install claude-hud

预期结果：提示 claude-hud 安装完成。

第三步：重载插件

/reload-plugins

预期结果：插件加载，无需重启 Claude Code。

第四步：配置状态栏

/claude-hud:setup

预期结果：进入引导流程，选择预设（Full / Essential / Minimal）与标签语言。

第五步：验证

发一条消息，观察输入框下方出现状态栏。预期结果：出现类似 [Opus] │ my-project git:(main*) 与 Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% 的两行显示。旧版 Claude Code 若未显示，重启一次会话即可。

常见踩坑（6条）

踩坑 1：Linux 安装报 EXDEV: cross-device link not permitted

• 现象：/plugin install 失败，报 EXDEV: cross-device link not permitted。
• 原因：老版本 Claude Code 在 /tmp（独立 tmpfs 文件系统）上安装插件时跨设备链接失败（上游 anthropics/claude-code#14799）。
• 解决：先升级 Claude Code（该 bug 已修复）；无法升级则设 mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude 再安装。

踩坑 2：Windows setup 提示「no JavaScript runtime was found」

• 现象：/claude-hud:setup 报找不到 JavaScript 运行时。
• 原因：Windows 上未安装 Node.js LTS（官方支持运行时）。
• 解决：winget install OpenJS.NodeJS.LTS，重启 shell 后再执行 setup。

踩坑 3：Windows 下 statusLine 不生效（Claude Code 2.1.x 切到 PowerShell 7 后）

• 现象：升级 Claude Code 后状态栏在 Windows 上不显示（#521）。
• 原因：Claude Code 2.1.x 将默认 shell 切到 PowerShell 7，与旧版 statusLine 配置不兼容。
• 解决：升级 Claude HUD 到最新版；或参考 issue 中给出的 PowerShell 配置 workaround。

踩坑 4：HUD 在 PowerShell 重启后消失（Windows 11）

• 现象：系统重启后 HUD 从 PowerShell 消失，但插件文件完好（#196）。
• 原因：Windows 11 下 PowerShell 会话状态恢复问题。
• 解决：重启 Claude Code 会话，或重新执行 /reload-plugins。

踩坑 5：Context 百分比虚高/翻倍

• 现象：advisor / 多轮迭代时上下文条显示约 2 倍占用、随后回落（#666）。
• 原因：cache_read 在部分轮次被重复计数。
• 解决：以回落后的稳定值为准；关注该 issue 的修复进展。

踩坑 6：用量显示异常（API 限速下）

• 现象：偶发用量显示为 0 或明显异常。
• 原因：Claude 订阅/用量 API 被限速时数据不可用（#193）。
• 解决：等限速窗口过去后自动恢复；属已知容错行为。

踩坑 7：macOS 上升级 Claude Code 2.x 后无法读取登录态

• 现象：升级 Claude Code 2.x 后 HUD 读不到账号/用量信息。
• 原因：Claude Code 2.x 改用 macOS Keychain 存储 OAuth 凭证，旧版 HUD 读取方式失效（#50）。
• 解决：升级 Claude HUD 到含 Keychain 支持的最新版本。

初级用法

1. 盯上下文水位：长会话里随时看 Context 条（绿→黄→红），快满时主动 /compact，避免被强制压缩。
2. 看子 Agent 在干嘛：开启 Agent 状态行，实时看到 ◐ explore [haiku]: Finding auth code 这类子 Agent 任务与耗时。
3. 跟 Todo 进度：开启 Todo 行，任务拆解后按 ▸ Fix authentication bug (2/5) 跟踪完成度。
4. 按预设快速配置：用 /claude-hud:configure 在 Full / Essential / Minimal 三个预设间切换，日常用 Essential 减少视觉干扰。
5. 识别模型与提供商：状态栏第一行会显示模型名，并尽量识别 Bedrock / Vertex / MiniMax 等提供商标签，方便确认当前计费通道。

高级玩法

1. 自定义阈值与颜色：编辑 HUD 配置文件，把上下文/用量的黄色、红色阈值调成符合自己工作流的比例，配色也可自定义。
2. 调整项目路径层级：把项目路径显示配置为 1-3 级目录深度，在 monorepo 里快速定位当前所在子项目（#32）。
3. 启用 Reason 指示器：开启 reasoning effort 指示，直观看到当前用 Opus 还是 Haiku 在做思考（#271）。
4. 切换上下文显示模式：用 contextValue 的 both 模式同时显示百分比与 token 数，适合需要精确 token 预算的场景（#263）。
5. 配合 Pro/Max 用量显示：Claude Pro/Max/Team 用户可开启用量限速条（Usage 条），把 5 小时滚动窗口的剩余额度直接显示在状态栏（#34）。
6. 配置持久化与多机同步：HUD 的配置是文件式的（自定义阈值、配色、布局都存成配置），可把一份配置复制到多台机器，配合终端方式 claude plugin install claude-hud@claude-hud 批量初始化。

小技巧

1. 安装后先跑 /claude-hud:setup 选「Essential」预设，用几天再逐步开 Full，避免信息过载。
2. 状态栏数据是原生上报、非估算，但仍有 300ms 防抖，别在极高频率交互时盯着逐 token 变化。
3. 更新 Claude Code 后若 HUD 消失，先 /reload-plugins，再考虑重启会话。
4. 用 claude plugin marketplace add / claude plugin install 的终端方式可批量初始化多台机器。
5. 关注上游 anthropics/claude-code 的 statusline API 变更，HUD 的兼容性主要受它影响。
6. 终端里用 claude plugin marketplace add jarrodwatts/claude-hud 可跳过会话内斜杠命令，适合脚本化初始化新机器。

常见问题 FAQ

Q1：Claude HUD 收费吗？

A：完全免费，MIT 开源。但它服务于 Claude Code，后者需要 Claude Pro（$20/月）或 Max（$100/月）订阅，或按量计费的 API Key。来源：Claude 定价页。

Q2：它和 ccusage 有什么区别？

A：ccusage 是独立 Web 用量看板，适合跨会话看账单/趋势；Claude HUD 是会话内实时状态栏，看当下上下文与活动。两者定位互补，常一起用。来源：ccusage 官网 与 Claude HUD README。

Q3：需要 tmux 或单独开窗口吗？

A：不需要。它基于 Claude Code 原生 statusline API，直接渲染在当前终端输入框下方，任意终端可用。来源：README How It Works。

Q4：支持哪些平台？

A：macOS / Windows / Linux 均支持；Windows 需 Node.js LTS 运行时。来源：README Install。

Q5：数据是估算的吗？

A：不是。Token 与上下文数据来自 Claude Code 原生上报，并随 Claude Code 报告的上下文窗口（含 1M context 会话）缩放。来源：README Key features。

进阶学习建议

• 吃透 statusline API：Claude HUD 本质是 statusline API 的消费者——Claude Code → stdin JSON → claude-hud → stdout，并解析 transcript JSONL 得到工具/Agent/Todo 活动。想给 Claude Code 写自己的可视化插件，先读通这条数据流。
• 研究 300ms 防抖与重渲染触发：HUD 在新助手消息、/compact、权限变更、vim 模式切换时重渲染并做 300ms 防抖，这是终端 UI 性能优化的一个可复用范本。
• 实战项目：给 HUD 加一个自定义 Provider 标签：参考 #652「第一行显示认证方式与登录账号」的改动思路，为你的 API 中转（如 Anthropic-compatible 网关）加一个可识别标签。
• 误区提示：不要根据 HUD 的 Context 百分比在极端高频交互下做实时决策——数据有防抖与多轮计数修正（见踩坑 5），以稳定后的读数为准。

参考链接

• Claude HUD GitHub 仓库
• Claude Code 官方文档
• Anthropic 定价页
• 上游 EXDEV bug 跟踪

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。