Claude HUD 速成指南：3 分钟跑通 Claude Code 的实时上下文状态栏-开发者社区

Claude HUD 速成指南：3 分钟跑通 Claude Code 的实时上下文状态栏

【免费下载链接】claude-hudA Claude Code plugin that shows what's happening - context usage, active tools, running agents, and todo progress项目地址: https://gitcode.com/GitHub_Trending/cl/claude-hud

上下文条突然变红，你改到一半的 prompt 还没调完。Claude HUD 把实时状态挂进终端底部状态栏：上下文用量、正在跑的工具、活跃子代理、待办进度，一眼看清当前 Claude Code 会话在干嘛。

30 秒装好并跑起来

前提是 Claude Code v1.0.80 以上、Node.js 18 以上。在 Claude Code 里敲三条命令：

/plugin marketplace add jarrodwatts/claude-hud /plugin install claude-hud /reload-plugins

再跑一次 setup，它会把 statusline 条目写进你的配置：

/claude-hud:setup

完成后随便发一条消息，HUD 就出现在底部，不用重启 Claude Code。Linux 装插件报EXDEV时，先执行mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude换掉临时目录再装；Windows 上 setup 提示找不到 JavaScript 运行时，先装 Node.js LTS。

跑长任务时盯住上下文消耗

长对话总会撞上上下文上限，等提示出现就晚了。Claude HUD 在状态栏第二行画一根上下文条，绿 → 黄 → 红三档变色，超过 85% 还会展开 token 分解，告诉你上下文花在哪了。订阅用户这行还会显示 5 小时、7 天两个窗口的用量和重置倒计时，心里有数还剩多少额度。

百分比不是估算值，是 Claude Code 通过 stdin 传进来的原生 token 数据，窗口大小跟着模型走，1M token 的会话也能对上。想看具体 token 而不是百分比，改一个配置项：

{ "display": { "contextValue": "tokens" } }

显示成45k/200k的形式。

多 Agent 并行时看清谁在干嘛

子代理一多就容易失控：谁在跑、跑到哪一步、跑了多久，全靠翻会话记录。打开活动行后，HUD 在底部列出每个子代理的名字、模型、任务和耗时，比如explore [haiku]: Finding auth code (2m 15s)；工具行滚动显示正在读、改、搜了哪些文件，todo 行标出任务完成到第几项。

这三行默认都是关的，有对应活动才会出现，想固定展示就在配置里打开：

{ "display": { "showTools": true, "showAgents": true, "showTodos": true } }

提交前确认分支没串

提错分支这种事比你想的多。状态栏第一行默认显示项目路径和 git 分支，分支名带*说明有未提交改动。再打开与远程的领先落后数和文件统计：

{ "gitStatus": { "showAheadBehind": true, "showFileStats": true } }

栏里就会长出git:(main ↑2 ↓1 * !3 +1 ?2)，几条提交没推、改了几个文件，一眼扫完。

调成你喜欢的样子

所有配置在~/.claude/plugins/claude-hud/config.json。跑/claude-hud:configure会带你走一遍预设和标签语言，你手改过的项都会保留。

按"想看多少"选预设：Full 全开，Essential 只留活动行加 git，Minimal 只剩模型名和上下文条。单行布局加两级路径：

{ "lineLayout": "compact", "pathLevels": 2 }

颜色想更醒目，直接改 colors 块（取值支持 8 个基础色名、0-255 色号、#十六进制）：

{ "colors": { "context": "cyan", "usage": "cyan", "warning": "yellow", "usageWarning": "magenta", "critical": "red" } }

踩坑速查

装完 setup 状态栏是空的：statusline 要等下一次交互才重绘，先发一条消息触发。还不行就重启 Claude Code，并确认环境里没设CLAUDE_HUD_DISABLE。

Linux 安装报 EXDEV：旧版本把/tmp挂在独立文件系统上，装插件跨盘失败。升级 Claude Code，或按前文办法用TMPDIR指到本地目录再装。

用量条不显示：这块数据只有 Pro/Max/Team 订阅才有。API key 登录或 Bedrock 用户没有 rate limit 数据，不显示属正常。

工具 / Agent / todo 行不出现：三行默认隐藏，且要有对应活动才渲染。想固定显示就把showTools、showAgents、showTodos设为 true。

git 信息缺失：当前目录不是 git 仓库，或配置里gitStatus.enabled被关了。按这两点依次排查。

给想深入的人

src/index.ts：入口，接收 Claude Code 经 stdin 传入的 JSON，协调整条数据流
src/transcript.ts：解析会话转录文件，抽出工具、agent、todo 信息
src/render/：每行的渲染模块，上下文条、工具、agent、git 都在这里
src/config.ts：配置读取、校验与分层合并
commands/：setup 与 configure 两条斜杠命令的源码

本地跑起来：

git clone https://gitcode.com/GitHub_Trending/cl/claude-hud cd claude-hud npm ci && npm run build npm test

下一步做什么

打开 Claude Code，跑一次/claude-hud:configure挑个预设，再把要的活动行打开、颜色改顺眼。状态栏稳定之后，写代码时就不用再分心确认任何事。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Claude HUD 速成指南：3 分钟跑通 Claude Code 的实时上下文状态栏