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

引言

"A Claude Code plugin that shows what's happening."

这是「一天一个开源项目」系列的第 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-preview-5-2转存失败，建议直接上传图片文件

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

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

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

使用场景

日常编码
- 随时看上下文是否快满，决定是否压缩或开新会话
- 看当前在编辑/读取哪个文件，工具是否卡住
调试与观察
- 观察子代理在做什么、跑了多久
- 看 Todo 推进到第几条，便于和 Claude 对齐进度
用量与配额管理
- Pro/Max/Team 用户看当日/当周期用量与 7 天占比，避免超限
多项目切换
- 通过路径与 Git 信息确认当前仓库与分支，减少误操作
终端党
- 不想用 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。

核心特性

原生 token 数据
- 使用 Claude Code 的 statusline API，展示的是真实 token 信息，而非估算值
约 300ms 刷新
- 状态栏以约 300ms 间隔更新，接近实时
无需额外窗口
- 不依赖 tmux 或新终端，直接在 Claude Code 的终端里、输入框下方展示
上下文条颜色
- 根据占用率绿→黄→红，高占用（如 85%+）可显示 token 细分
工具 / Agent / Todo 行
- 可选显示：工具活动行、Agent 状态行、Todo 进度行（默认可关闭，需在配置中开启）
三种预设
- Full：工具、Agent、Todo、Git、用量、时长等尽量全开
- Essential：活动行 + Git，信息适中
- Minimal：仅模型名与上下文条
布局与路径
- lineLayout：expanded（多行）或 compact（单行）
- pathLevels：1～3 层目录深度
Git 信息
- 分支、脏标记（*）、超前落后（↑N ↓N）、文件统计（!M +A ✘D ?U）均可开关
用量展示（Pro/Max/Team）
- 显示限流用量条与 7 天占比；可设阈值（如 80%）仅在接近上限时显示 7 天
配置方式
- 引导式：/claude-hud:configure；高级用户可直接改 config.json

项目优势

对比项	Claude HUD	无插件 / 仅日志	自建监控脚本
可见性	常驻输入下方，实时	需切屏或翻日志	视实现而定
数据来源	原生 statusline + transcript	无或自行解析	需自己对接
配置	预设 + 细项 + config.json	无	需自维护
安装	3 条命令，无需改 Claude 源码	无	需集成环境
用量展示	支持 Pro/Max/Team	无	需自己实现

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

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