解决 Claude Code 使用焦虑的插件

claude-hud：让你的终端拥有一块「仪表盘」

---

你有没有过这样的经历：正沉浸在 Claude Code 的编程会话中，突然感到一阵莫名的焦虑——context 还剩多少？AI 现在到底在干什么？任务有没有卡住？这种「信息黑盒」的感觉，是很多 Claude Code 用户的共同困扰。

今天介绍的这款开源插件 claude-hud，就是专门为这种焦虑而生的。

---

什么是「使用焦虑」？

Claude Code 的终端界面在默认状态下，几乎不提供任何关于「当前状态」的视觉反馈。你看不到：

• context 窗口还剩多少空间（直到它快满了你才后知后觉）
• AI 正在调用哪些工具、读取哪些文件
• 有没有子 Agent 在后台运行，它们进展如何
• 当前 session 的 API 用量消耗了多少

这就像开车时仪表盘全黑——你不知道油箱还剩多少，也不知道引擎温度有没有异常，只能靠感觉开。一旦 context 溢出，整个对话的连贯性就会崩溃，之前做的一切可能都要重来。

---

claude-hud 是什么？

claude-hud 是由开发者 Jarrod Watts 创作的一款 Claude Code 插件，项目托管在 GitHub 上（github.com/jarrodwatts/claude-hud）。它利用 Claude Code 原生的 statusline API，在终端底部渲染一条持续可见的「抬头显示器（HUD）」，让你随时掌握会话状态。

安装完成后，你会在终端输入框下方看到类似这样的信息：

[Opus | Pro] █████░░░░░ 45% | my-project git:(main) | 5h: 25% | ⏱️ 5m
◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2
◐ explore [haiku]: Finding auth code (2m 15s)
▸ Fix authentication bug (2/5)

一切一目了然，不需要手动输入任何查询命令。

---

核心功能详解

① 上下文窗口可视化

HUD 会以进度条的形式实时显示当前 context 的占用比例，颜色会随着占用量增加而变化：绿色 → 黄色 → 红色。数据直接来自 Claude Code，精确无误，不是估算。

💡 提示：当进度条变黄时，建议开始考虑是否需要压缩对话历史或开启新 session，以免 context 溢出导致 AI「失忆」。

② 工具活动追踪

你可以实时看到 Claude 正在对哪些文件执行什么操作，例如读取（Read）、编辑（Edit）、搜索（Grep）等，及其执行次数。这在复杂的多文件任务中尤为有用——你能判断 AI 是否在做正确的事，而不是在无谓地反复读取同一个文件。

③ 子代理状态

当 Claude 启动子 Agent（subagent）处理子任务时，HUD 会显示每个 Agent 的名称、当前任务描述及运行时长。这让复杂的 agentic 工作流变得透明，你能清楚地知道哪个 Agent 在做什么、是否有 Agent 卡住了。

④ Todo 任务进度

如果 Claude 规划了一个包含多个步骤的 Todo 列表，HUD 会以「当前步骤/总步骤」的格式显示进度，例如 ▸ Fix authentication bug (2/5)。这给了你清晰的任务完成感。

⑤ API 用量监控

对于 Claude Pro、Max 和 Team 订阅用户，HUD 默认显示 5 小时内的用量消耗百分比。当 7 天累计用量超过 80% 时，还会额外显示 7 天维度的消耗情况。再也不用担心「配额用完了还不知道」的情况。

---

技术架构：简洁而高效

claude-hud 的架构非常轻量，数据流向如下：

Claude Code → stdin JSON → claude-hud → stdout → 显示在终端底部
                         ↘ transcript JSONL（工具、Agent、Todo）

插件约每 300ms 被 Claude Code 调用一次，从两个数据源获取信息：

• stdin JSON：由 Claude Code 直接注入，包含模型名称、context 用量等原生精确数据
• transcript JSONL：插件解析会话记录文件，提取工具调用、Agent 状态和 Todo 列表

得益于使用了 Claude Code 的原生 statusline API，整个插件无需额外的终端窗口或 tmux，在任意终端环境中都能正常工作。

---

如何安装？

安装过程极为简单，只需在 Claude Code 中执行两条命令：

1. 添加插件市场来源：
   /plugin marketplace add jarrodwatts/claude-hud
2. 安装插件：
   /plugin install claude-hud

安装完成后无需重启，HUD 立即出现在终端底部。

⚠️ Linux 用户注意：若安装时遇到 EXDEV: cross-device link not permitted 报错，请先执行 mkdir -p ~/.cache/t 再重试，这是 Claude Code 平台的已知限制。

---

个性化配置

claude-hud 提供了丰富的配置选项。运行 /claude-hud:configure 可以通过交互式向导选择预设布局并按需开关各个显示元素；高级用户也可以直接编辑配置文件：

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

可配置的选项包括：布局模式（紧凑/展开）、各元素的显示顺序、颜色主题、Git 状态显示详细程度、用量告警阈值等。

---

总结

claude-hud 解决的是一个真实存在但常被忽视的体验问题：信息透明度。在 AI 辅助编程日益普及的今天，我们需要能够观察和理解 AI 行为的工具，而不仅仅是被动地等待结果。

这款插件把 Claude Code 从一个「黑盒子」变成了一个「透明玻璃盒」。如果你经常使用 Claude Code 进行复杂的开发任务，强烈推荐把它加入你的工具箱——安装成本几乎为零，但带来的掌控感和安心感是实实在在的。

---

项目地址：https://github.com/jarrodwatts/claude-hud