jarrodwatts/claude-hud · 上手攻略
- 仓库：jarrodwatts/claude-hud
- 链接：https://github.com/jarrodwatts/claude-hud
- 分类：skill
- 作者：Jay
- 更新：2026-07-13
这是什么
Claude HUD 是 Claude Code 的一个插件（Plugin），在终端底部状态栏实时显示当前会话的关键信息——包括上下文窗口使用量、Token 消耗速率、正在调用的工具、最近的 Agent 活动，以及 Todo 任务进度。
它的本质是：利用 Claude Code 原生的 statusline API，把 Claude Code 内部运行状态通过一个 HUD 可视化出来，不需要独立窗口，不需要 tmux，在你已有的任何终端里直接可见。
一句话理解：给 Claude Code 装一个实时仪表盘。
解决什么问题
Claude Code 用户普遍面临一个痛点：Context Window 盲区——你不知道上下文还剩多少、Claude 正在用什么工具、跑着什么子 Agent，等发现上下文快爆了的时候已经来不及了，只能接受降级的输出质量。
Claude HUD 把这些黑盒状态变得完全透明：
- 上下文快满了 → 状态条变红，提前知道
- Claude 读错了文件 → 工具活动栏立刻看到
Read ×3 - 子 Agent 跑偏了 → Agent 追踪栏实时显示各 Agent 状态
- 任务进度不明 → Todo 栏显示
Fix authentication bug (2/5)
快速安装
前置要求
- Claude Code 已安装并正常运行
- Linux/macOS/Windows（Windows 需要 Node.js LTS 运行时）
Step 1：添加插件市场
在 Claude Code 终端内执行：
/plugin marketplace add jarrodwatts/claude-hud
Step 2：安装插件
/plugin install claude-hud
⚠️ Linux 用户特别注意：/tmp 在很多 Linux 发行版是 tmpfs，会导致 EXDEV: cross-device link not permitted 错误。修复方法：
mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude
之后在那个 session 里执行安装命令。
⚠️ Windows 用户：如果 setup 提示找不到 JavaScript 运行时，先安装 Node.js LTS：
winget install OpenJS.NodeJS.LTS
重启 shell 后重新运行 /plugin install claude-hud。
Step 3：运行初始化配置
/reload-plugins
/claude-hud:setup
完成后重启 Claude Code，HUD 即会出现在终端底部状态栏。
核心功能与界面
Claude HUD 分两行显示：
[Opus] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)
◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2 ← 工具活动
◐ explore [haiku]: Finding auth code (2m 15s) ← Agent 状态
▸ Fix authentication bug (2/5) ← Todo 进度
第一行： - 模型名称 + Provider（如 Bedrock / Vertex / Enterprise） - 项目路径（可配置显示几级目录） - Git 分支状态（dirty 标记、ahead/behind 远程数量） - Context 健康条（绿→黄→红，上下文消耗进度） - Usage 消耗条（Token 消耗速率，直观显示还剩多少）
第二行： - 工具活动：实时显示正在读/写/搜索哪些文件 - Agent 追踪：如果有子 Agent 在跑，显示名称和当前任务 - Todo 进度：完成比例
配置与自定义
预设模式
/claude-hud:configure
进入引导配置，可选三种预设：
| 预设 | 显示内容 |
|---|---|
| Full | 全部开启：工具、Agent、Todo、Git、Usage、耗时 |
| Essential | 仅工具活动 + Git 状态，最少干扰 |
| Minimal | 仅模型名 + Context 状态条 |
配置文件
高级配置直接编辑 ~/.claude/plugins/claude-hud/config.json，部分可配置项：
{
"language": "zh-Hans", // en | zh | zh-Hans
"lineLayout": "expanded", // expanded | compact（单行）
"pathLevels": 2, // 显示几级目录
"display.showContextBar": true, // 显示上下文健康条
"display.showProvider": true, // 显示 Provider 标签
"gitStatus.enabled": true, // 显示 Git 状态
"gitStatus.showDirty": true, // 显示 * 未提交标记
"elementOrder": ["project", "context", "usage", "tools", "agents", "todos"]
}
典型适用场景
| 场景 | 为什么有用 |
|---|---|
| 长会话编程（>1h） | 上下文快满时提前知道，避免 Claude 开始说废话 |
| 多 Agent 并行任务 | 同时监控多个子 Agent 的进度和状态 |
| 文件修改密集任务 | 实时看到 Claude 在读/编辑哪些文件，发现读错立即纠正 |
| 多任务 Todo 推进 | 直观看到每个子任务的完成比例 |
| Git 协作（dirty state） | 看到当前分支的 dirty 状态，避免意外提交 |
坑与注意
- Linux /tmp 问题：如果安装时报 EXDEV 错误，先设置
TMPDIR=~/.cache/tmp再启动 Claude Code，这是 Claude Code 平台限制，非插件 Bug。 - Windows Node.js 依赖：Windows 上 setup 需要 Node.js LTS 运行时，没有的话 setup 会静默失败。
- 不是独立窗口：HUD 渲染在 Claude Code 的 statusline 里，不是单独的 GUI 窗口，如果终端本身不支持 ANSI 颜色码或不支持 statusline，可能显示不完整。
- Token 计数来源：使用的是 Claude Code 原生 token 数据（不是估算），但上下文上限取决于当前会话配置的 context window size（新版已支持 1M context）。
- 刷新频率：HUD 每 300ms 更新一次，高频工具调用（如大量文件搜索）可能让工具活动栏变化很快，这是正常现象。
- 不能禁用 JSONL 读取：HUD 工作原理是解析 transcript JSONL 文件，如果你的项目对文件写入有严格限制（如只读模式），HUD 可能无法正常工作。
与同类对比
| 维度 | Claude HUD | Claude Code 内置 /status |
tmux 状态栏 | Cursor AI HUD |
|---|---|---|---|---|
| 显示内容 | 上下文、工具、Agent、Todo、Git | 简单上下文 % | 通用终端信息 | 偏 IDE 内 |
| 安装方式 | Claude Code Plugin | 内置 | 终端配置 | IDE 插件 |
| 实时性 | 300ms 刷新，原生数据 | 手动触发 | 取决于刷新频率 | 取决于 IDE |
| Agent 追踪 | ✅ | ❌ | ❌ | 有限 |
| Todo 可视化 | ✅ | ❌ | ❌ | 有限 |
| 平台 | Claude Code 通用 | Claude Code | 任意终端 | Cursor IDE |
一句话推荐结论
如果你重度使用 Claude Code，Claude HUD 是提升效率的最小成本方案——装上就能用，每 300ms 自动刷新，上下文快爆了再也不后知后觉。