一天一个开源项目（第34篇）：Claude HUD - Claude Code 的实时状态栏，一眼看清会话在发生什么

引言

这是「一天一个开源项目」系列的第 34 篇文章。今天介绍的项目是 Claude HUD（GitHub）。

用 Claude Code 写代码时，上下文用了多少、当前在跑哪些工具、有没有子代理在干活、Todo 做到第几条——这些信息往往要翻日志或等提示才看得见。Claude HUD 把这些都搬到了终端里、输入框下方：一条（或几条）常驻状态栏，实时显示上下文健康度、工具活动、Agent 状态、Todo 进度，数据来自 Claude Code 的 statusline API 和 transcript，约 300ms 刷新，无需另开窗口或 tmux，用任何终端都能用。

为什么值得看？

• 实时可见：上下文条（绿→黄→红）、用量条、工具/Agent/Todo 一行看清
• ️ 原生集成：用 Claude Code 的 statusline API，不用估 token，数据准确
• 常驻输入下方：不抢焦点、不占新窗口，始终在眼前
• ️ 可配置：预设 Full/Essential/Minimal，或细调每项显示与布局
• 标准插件：通过 /plugin marketplace 安装，/claude-hud:setup 即用
• Pro/Max/Team：支持用量限制展示（订阅用户）

你将学到什么

• Claude HUD 的定位与典型展示内容（上下文、工具、Agent、Todo、Git、用量）
• 安装与配置流程（marketplace、install、setup/configure）
• 工作原理：stdin JSON + transcript JSONL，约 300ms 更新
• 配置项概览：lineLayout、pathLevels、gitStatus、display 等
• 预设与手动编辑 config.json
• 与「无 HUD」或自建监控方式的对比
• 使用与排错小贴士

前置知识

• 正在或打算使用 Claude Code（终端版）
• 了解「上下文窗口」「token」等基本概念更佳
• 本地需 Claude Code v1.0.80+、Node.js 18+ 或 Bun

项目背景

项目简介

Claude HUD 是面向 Claude Code 的实时状态栏插件。它在你的终端里、输入框下方，常驻显示当前会话的「在发生什么」：

• 项目路径：当前目录（可配置 1～3 层）
• 上下文健康：上下文窗口占用（进度条 + 颜色），避免突然爆窗
• 工具活动：正在/已完成的 Read、Edit、Grep 等及次数
• Agent 状态：当前子代理、模型、任务描述与已运行时间
• Todo 进度：任务完成情况（如 2/5）
• Git：分支、脏状态、超前落后、文件统计（可选）
• 用量：Pro/Max/Team 用户的限流用量与 7 天占比（可选）

数据来自 Claude Code 的原生 statusline API（含真实 token 数据）和 transcript JSONL（解析工具、Agent、Todo），更新频率约 300ms，不依赖估算。

面向的用户：

• 日常用 Claude Code 写代码、排错的开发者
• 需要随时掌握上下文与用量，避免超限或卡顿的用户
• 想观察工具调用与子代理行为、做调试或学习的人
• 希望终端里「一眼看清会话状态」、不想切窗口的人

作者/团队介绍

• 作者：jarrodwatts（GitHub）
• 仓库：开源插件，带完整 README、CHANGELOG、CONTRIBUTING、测试与发布说明

项目数据

• ⭐ GitHub Stars: 约 3.7k+（GitHub）
• Forks: 约 166
• 仓库状态: 持续维护，含 .claude-plugin/、commands/、src/、dist/、tests/
• License: MIT
• 文档: README 含安装、配置、选项、排错；Claude Code Marketplace 有介绍

技术栈：TypeScript、Node.js 18+ 或 Bun，通过 Claude Code 的 plugin 与 statusline API 集成。

主要功能

核心作用

Claude HUD 的核心作用是：在 Claude Code 终端里提供一条（或多条）常驻的实时状态栏，让你不用离开当前会话就能看到：

1. 上下文用量：进度条 + 百分比（或 token 数），颜色随占用升高变化（绿→黄→红），高占用时还可显示 token 细分
2. 工具活动：当前在执行或刚执行完的工具（如 Edit、Read、Grep）及次数
3. 子代理状态：正在跑的 Agent、所用模型、任务描述、已运行时间
4. Todo 进度：当前任务列表完成情况（如 2/5）
5. 项目与 Git：当前路径（1～3 层）、分支、是否有未提交改动、超前落后、文件统计（可配置）
6. 用量限制：Pro/Max/Team 用户的限流用量条与 7 天占比（可选）

从而在不打断输入、不另开窗口的前提下，提升对会话的「可观测性」。

使用场景

1. 日常编码

   • 随时看上下文是否快满，决定是否压缩或开新会话
   • 看当前在编辑/读取哪个文件，工具是否卡住

2. 调试与观察

   • 观察子代理在做什么、跑了多久
   • 看 Todo 推进到第几条，便于和 Claude 对齐进度

3. 用量与配额管理

   • Pro/Max/Team 用户看当日/当周期用量与 7 天占比，避免超限

4. 多项目切换

   • 通过路径与 Git 信息确认当前仓库与分支，减少误操作

5. 终端党

   • 不想用 tmux 或额外窗口，希望一切都在当前终端里完成

快速开始

环境：Claude Code v1.0.80+，Node.js 18+ 或 Bun。

在 Claude Code 会话里依次执行：

# Step 1：添加插件市场（若尚未添加）
/plugin marketplace add jarrodwatts/claude-hud

# Step 2：安装插件
/plugin install claude-hud

# Step 3：配置状态栏（首次会引导预设与选项）
/claude-hud:setup

完成后 HUD 会立即出现在输入框下方，无需重启。

Linux 用户：若安装时报错 EXDEV: cross-device link not permitted（因 /tmp 为独立文件系统），可先设置 TMPDIR 再启动 Claude Code 并安装：

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

然后在同一会话中执行上述 Step 2、Step 3。详见 Claude Code 相关 Issue。

后续调整：随时运行 /claude-hud:configure 进入引导式配置，或直接编辑 ~/.claude/plugins/claude-hud/config.json。

核心特性

1. 原生 token 数据

   • 使用 Claude Code 的 statusline API，展示的是真实 token 信息，而非估算值

2. 约 300ms 刷新

   • 状态栏以约 300ms 间隔更新，接近实时

3. 无需额外窗口

   • 不依赖 tmux 或新终端，直接在 Claude Code 的终端里、输入框下方展示

4. 上下文条颜色

   • 根据占用率绿→黄→红，高占用（如 85%+）可显示 token 细分

5. 工具 / Agent / Todo 行

   • 可选显示：工具活动行、Agent 状态行、Todo 进度行（默认可关闭，需在配置中开启）

6. 三种预设

   • Full：工具、Agent、Todo、Git、用量、时长等尽量全开
   • Essential：活动行 + Git，信息适中
   • Minimal：仅模型名与上下文条

7. 布局与路径

   • lineLayout：expanded（多行）或 compact（单行）
   • pathLevels：1～3 层目录深度

8. Git 信息

   • 分支、脏标记（*）、超前落后（↑N ↓N）、文件统计（!M +A D ?U）均可开关

9. 用量展示（Pro/Max/Team）

   • 显示限流用量条与 7 天占比；可设阈值（如 80%）仅在接近上限时显示 7 天

10. 配置方式

    • 引导式：/claude-hud:configure；高级用户可直接改 config.json

项目优势

为什么选 Claude HUD？

• 专为 Claude Code 设计，与 statusline/transcript 深度集成，数据准确、刷新快
• 零额外窗口，终端内即可获得「仪表盘」式视图
• 预设 + 可配置，既适合开箱即用，也适合按需精简或扩展
• 开源、文档齐全，遇到问题可查 README 与 Issues

项目详细剖析

架构与数据流

README 给出的数据流概括为：

Claude Code → stdin JSON → claude-hud → stdout → 显示在终端
                ↘ transcript JSONL（tools, agents, todos）

• stdin JSON：来自 Claude Code 的 statusline 相关数据（含原生 token 等），供 HUD 渲染第一行与上下文/用量条等
• transcript JSONL：会话的 transcript，claude-hud 解析其中的工具调用、子代理、Todo，用于工具行、Agent 行、Todo 行
• stdout：渲染后的状态栏文本输出到终端，由 Claude Code 显示在输入框下方
• 更新频率：约 300ms 一次，在保证实时感的同时避免刷屏

项目结构（概要）

• .claude-plugin/：Claude Code 插件元数据与入口
• commands/：插件命令（如 setup、configure）
• src/：核心逻辑（解析 statusline、transcript，生成状态栏内容）
• dist/：构建产物
• tests/：测试

配置项概览

配置可通过 /claude-hud:configure 或直接编辑 ~/.claude/plugins/claude-hud/config.json 完成。README 中主要选项包括：

布局与路径

• lineLayout：expanded | compact
• pathLevels：1 | 2 | 3（项目路径显示层数）

Git（gitStatus）

• enabled：是否显示 Git
• showDirty：未提交改动标记（*）
• showAheadBehind：↑N ↓N
• showFileStats：!M +A D ?U

显示（display）

• showModel：是否显示模型名（如 [Opus]）
• showContextBar：是否显示上下文条
• contextValue：percent 或 tokens
• showUsage：是否显示用量（Pro/Max/Team）
• usageBarEnabled：用量是否用进度条
• sevenDayThreshold：达到该百分比时显示 7 天用量（0 表示始终显示）
• showTokenBreakdown：高上下文时是否显示 token 细分
• showTools / showAgents / showTodos：是否显示工具/Agent/Todo 行
• showConfigCounts、showDuration、showSpeed 等：按需开启

无效 JSON 或非法值会导致静默回退到默认配置；可删除 config 后重新运行 /claude-hud:configure 生成新配置。

用量与订阅

• 用量展示依赖 Claude Code 的 OAuth 登录，仅对 Pro / Max / Team 订阅用户可用（按限流计费），API 用户为按 token 计费，无此类用量条。
• 使用 AWS Bedrock 时界面显示为 "Bedrock"，用量由 AWS 侧管理，HUD 不显示用量条。
• 若用量不显示：确认已用 Pro/Max/Team 账号登录（非 API Key）、配置中 display.showUsage 未设为 false。

排错提示（README）

• 配置不生效：检查 JSON 语法、pathLevels 与 lineLayout 取值；必要时删 config 再跑 /claude-hud:configure。
• Git 不显示：确认当前在 Git 仓库内，且 gitStatus.enabled 未为 false。
• 工具/Agent/Todo 行不出现：在配置中打开 showTools、showAgents、showTodos；且这些行仅在有对应活动时才会显示。

项目地址与资源

官方资源

• GitHub: github.com/jarrodwatts…
• README: 安装、配置、选项、示例、排错
• Issues: GitHub Issues
• Claude Code Marketplace: jarrodwatts/claude-hud

相关资源

• Claude Code：需 v1.0.80+；Linux 安装问题见 anthropics/claude-code#14799
• 插件开发：可参考仓库内 CONTRIBUTING、TESTING、RELEASING

适用人群

• Claude Code 日常用户：希望在不离开终端的前提下掌握上下文、工具、Agent、Todo、用量
• Pro/Max/Team 用户：需要直观看到限流与 7 天用量
• 喜欢可观测性：想看清「当前会话在发生什么」的开发者
• 终端优先：不想依赖 tmux 或额外窗口，希望一切集中在一个会话里

欢迎来我中的个人主页找到更多有用的知识和有趣的产品