Claude HUD 实时状态栏：告别Claude Code盲等，10K星标爆火安装与配置全指南

10K⭐爆火！Claude HUD：给 Claude Code 装上“状态栏”，终于知道它在干嘛了

Image

01 为什么用 Claude Code 总像开“盲盒”？

你是不是经常遇到这种情况：

让 Claude Code 帮你写代码，它一顿输出，你却完全摸不到头绪：

  • 上下文用量还剩多少？是不是快满了？
  • 它在读哪个文件？改了什么？
  • 有没有启动子 agent？正在进行什么操作？
  • Todo 列表已经完成了几个？

整个过程就像个不透明的盒子。

你只能干等它输出，中间的细节一概不知。有时候上下文快被塞爆了，它还在读取无关文件，你想干预都来不及。

这就是“上下文盲区”（Context Blindness）。简单来说，Claude Code 原生的输出太克制，你没办法实时掌握它的动态。

Claude HUD 正是为此而生。

02 Claude HUD 是什么？

一句话：给 Claude Code 装上一块实时状态栏，所有关键信息一目了然。

Image

  • GitHub 星标：10,000+
  • 作者：Jarrod Watts（知名开发者工具创作者）
  • 用户评价：“Finally know what’s happening!”

核心思路非常直接：利用 Claude Code 原生的 statusline API，在输入框下方动态显示实时状态。

作者的说法是：“Native token data from Claude Code — not estimated. Updates every ~300ms.”

最终效果就是：上下文使用率、各类工具活动、子 agent 状态、Todo 进度，全部实时可见。

03 你能看到什么？

Image

第一行：基础信息

[Opus | Max] │ my-project git:(main*)
模型名称（Opus/Max/Bedrock）
项目路径（可配置 1‑3 级目录）
Git 分支及未提交标记

第二行：核心指标

Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)
上下文条：绿色 → 黄色 → 红色，直观展示使用率
用量条：Pro/Max/Team 用户可见 7 天用量（API 用户不可见）

第三行：实时活动

◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2
◐ explore [haiku]: Finding auth code (2m 15s)
▸ Fix authentication bug (2/5)
工具活动：读、编辑、搜索文件
Agent 状态：子 agent 正在做什么、跑了多久
Todo 进度：已完成/总任务数

Image

04 三步安装与配置

第一步：添加 marketplace

/plugin marketplace add jarrodwatts/claude-hud

第二步：安装插件

/plugin install claude-hud

⚠️ Linux 用户请注意：若 /tmp 是独立文件系统，安装可能失败。先执行下面的命令，然后在新的会话里安装：

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

第三步：配置状态栏

/claude-hud:setup

完成！重启 Claude Code 即可看到效果。

05 三种预设模式

模式显示内容适用场景
Full全部元素：工具、agent、todo、git、用量、时长复杂项目，需要全方位监控
Essential活动行 + Git 状态，最小信息干扰日常开发
Minimal核心：模型名 + 上下文条追求极简

配置命令：

/claude-hud:configure

引导流程会带你逐步选择。高级设置（颜色、阈值）可以通过编辑配置文件完成：

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

06 实战测试

场景 1：小型脚本（约 100 行）

  • HUD 模式：Minimal
  • 结果：✅ 上下文条完全够用
  • 感受：简单项目不需要太多信息，Minimal 恰到好处。

场景 2：Web 应用（约 2,000 行）

  • HUD 模式：Essential
  • 结果：✅ 工具活动 + Git 状态非常实用
  • 感受：可以实时看到 Claude 在修改哪个文件，心里踏实。

场景 3：大型重构（10,000 行以上 + 多 agent）

  • HUD 模式：Full
  • 结果：✅ 子 agent 追踪与 Todo 进度是关键
  • 感受：终于知道 5 个子 agent 分别在干什么，不用再“盲目等待”。

07 高级配置

自定义颜色

{
  "colors": {
    "context": "cyan",
    "usage": "cyan",
    "warning": "yellow",
    "usageWarning": "magenta",
    "critical": "red"
  }
}

支持的颜色：red、green、yellow、magenta、cyan、brightBlue、brightMagenta。

Git 状态增强

{
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": true
  }
}

用量监控

{
  "display": {
    "showUsage": true,
    "sevenDayThreshold": 80,
    "showDuration": true,
    "showSpeed": false
  }
}

08 常见问题

HUD 不显示？
重启 Claude Code（配置需重启才会生效）。macOS 用户请完全退出后再运行 claude。

用量不显示？
确认你是 Pro/Max/Team 订阅（API 用户不可见），检查 display.showUsage 不为 false。AWS Bedrock 模型会显示 “Bedrock” 且隐藏用量（由 AWS 管理）。

Git 状态缺失？
确保当前位于 Git 仓库内，并检查 gitStatus.enabled 不为 false。

配置不生效？
检查 JSON 语法是否有误（无效 JSON 会静默回退到默认值）。可以删除配置文件后重新运行 /claude-hud:configure。

09 Claude HUD 与其他工具

工具类型核心价值
Claude HUD状态监控实时可视化，零干扰
Get Shit Done元提示系统任务规划 + 上下文工程
SpecKit规范驱动需求文档 + 验收测试

GSD + HUD 是绝配：GSD 负责规划，HUD 负责监控执行。

10 值不值得装？

值得装，如果：

✅ 你每天都用 Claude Code
✅ 项目具有一定复杂度
✅ 受够了“不知道它在干什么”
✅ 想实时监控上下文使用率

不值得装，如果：

❌ 只是偶尔用用
❌ 项目都很简单
❌ 偏好极简输出

11 最后说句实话

Claude HUD 不是魔法。它不会让 Claude 写代码变得更快，但会让你更有掌控感。

用作者的话来说：

“Claude Code → stdin JSON → claude-hud → stdout → displayed in your terminal”

就是这么简单。但它解决了一个真实的问题：AI 编程工具的“黑盒状态”。

Claude HUD 通过实时状态栏，让 AI 编程变得透明、可预测、可干预。

那句“Finally know what’s happening!”的确说出了很多人的心声。

🔗 项目地址：

https://github.com/jarrodwatts/claude-hud