引言“A Claude Code plugin that shows what’s happening.”这是「一天一个开源项目」系列的第 34 篇文章。今天介绍的项目是Claude HUDGitHub。用 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的实时状态栏插件。它在你的终端里、输入框下方常驻显示当前会话的「在发生什么」项目路径当前目录可配置 13 层上下文健康上下文窗口占用进度条 颜色避免突然爆窗工具活动正在/已完成的 Read、Edit、Grep 等及次数Agent 状态当前子代理、模型、任务描述与已运行时间Todo 进度任务完成情况如 2/5Git分支、脏状态、超前落后、文件统计可选用量Pro/Max/Team 用户的限流用量与 7 天占比可选数据来自 Claude Code 的原生 statusline API含真实 token 数据和transcript JSONL解析工具、Agent、Todo更新频率约300ms不依赖估算。面向的用户日常用 Claude Code 写代码、排错的开发者需要随时掌握上下文与用量避免超限或卡顿的用户想观察工具调用与子代理行为、做调试或学习的人希望终端里「一眼看清会话状态」、不想切窗口的人作者/团队介绍作者jarrodwattsGitHub仓库开源插件带完整 README、CHANGELOG、CONTRIBUTING、测试与发布说明项目数据⭐GitHub Stars: 约 3.7kGitHubForks: 约 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 终端里提供一条或多条常驻的实时状态栏让你不用离开当前会话就能看到上下文用量进度条 百分比或 token 数颜色随占用升高变化绿→黄→红高占用时还可显示 token 细分工具活动当前在执行或刚执行完的工具如 Edit、Read、Grep及次数子代理状态正在跑的 Agent、所用模型、任务描述、已运行时间Todo 进度当前任务列表完成情况如 2/5项目与 Git当前路径13 层、分支、是否有未提交改动、超前落后、文件统计可配置用量限制Pro/Max/Team 用户的限流用量条与 7 天占比可选从而在不打断输入、不另开窗口的前提下提升对会话的「可观测性」。使用场景日常编码随时看上下文是否快满决定是否压缩或开新会话看当前在编辑/读取哪个文件工具是否卡住调试与观察观察子代理在做什么、跑了多久看 Todo 推进到第几条便于和 Claude 对齐进度用量与配额管理Pro/Max/Team 用户看当日/当周期用量与 7 天占比避免超限多项目切换通过路径与 Git 信息确认当前仓库与分支减少误操作终端党不想用 tmux 或额外窗口希望一切都在当前终端里完成快速开始环境Claude Code v1.0.80Node.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/tmpTMPDIR~/.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仅模型名与上下文条布局与路径lineLayoutexpanded多行或compact单行pathLevels13 层目录深度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 JSONLtools, agents, todosstdin JSON来自 Claude Code 的 statusline 相关数据含原生 token 等供 HUD 渲染第一行与上下文/用量条等transcript JSONL会话的 transcriptclaude-hud 解析其中的工具调用、子代理、Todo用于工具行、Agent 行、Todo 行stdout渲染后的状态栏文本输出到终端由 Claude Code 显示在输入框下方更新频率约 300ms 一次在保证实时感的同时避免刷屏项目结构概要.claude-plugin/Claude Code 插件元数据与入口commands/插件命令如setup、configuresrc/核心逻辑解析 statusline、transcript生成状态栏内容dist/构建产物tests/测试配置项概览配置可通过/claude-hud:configure或直接编辑~/.claude/plugins/claude-hud/config.json完成。README 中主要选项包括布局与路径lineLayoutexpanded|compactpathLevels1 | 2 | 3项目路径显示层数GitgitStatusenabled是否显示 GitshowDirty未提交改动标记*showAheadBehind↑N ↓NshowFileStats!M A ✘D ?U显示displayshowModel是否显示模型名如 [Opus]showContextBar是否显示上下文条contextValuepercent或tokensshowUsage是否显示用量Pro/Max/TeamusageBarEnabled用量是否用进度条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: https://github.com/jarrodwatts/claude-hudREADME: 安装、配置、选项、示例、排错Issues: GitHub IssuesClaude Code Marketplace: jarrodwatts/claude-hud相关资源Claude Code需 v1.0.80Linux 安装问题见 anthropics/claude-code#14799插件开发可参考仓库内 CONTRIBUTING、TESTING、RELEASING适用人群Claude Code 日常用户希望在不离开终端的前提下掌握上下文、工具、Agent、Todo、用量Pro/Max/Team 用户需要直观看到限流与 7 天用量喜欢可观测性想看清「当前会话在发生什么」的开发者终端优先不想依赖 tmux 或额外窗口希望一切集中在一个会话里欢迎来我中的个人主页找到更多有用的知识和有趣的产品