Claude HUD 实战指南：在 Claude Code 状态栏里监控上下文、工具与子代理

Claude HUD 实战指南：在 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

Claude HUD 是一个 Claude Code 插件，它把上下文占用、活跃工具、运行中的子代理和待办进度实时画在输入框下方的状态栏里。不需要 tmux、不需要额外窗口，它走的是 Claude Code 原生的 statusline 接口：Claude Code 通过 stdin 传入 JSON，插件解析后输出到终端，每次交互后重新渲染（300ms 防抖）。下面记录一遍从安装到常用配置的实际操作。

什么情况下值得装它

这个插件解决的不是"有没有数据"的问题，而是"数据出现在你视线里"的问题。三种典型场景：

• 长会话容易撑爆上下文：上下文条绿→黄→红的渐变让你在被逼着/compact之前就做出决策，而不是看到报错才回头找。
• 子代理并行干活：Explore、Task这类子代理在后台跑的时候，默认界面里完全看不到它们，HUD 会把每个代理的任务描述和运行时长列出来。
• 多人共用同一台开发机或远程会话：状态栏上的项目路径、git 分支、模型名（含 Bedrock/Vertex 这类 provider 标签）能避免你分不清当前会话挂在哪。

前提条件不低不复杂：Claude Code v1.0.80 以上；macOS/Linux 需要 Node.js 18+ 或 Bun，Windows 需要 Node.js 18+。

3 条命令完成安装

在 Claude Code 会话内依次执行：

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

然后跑配置向导：

/claude-hud:setup

向导会帮你检测 JavaScript 运行时、写 statusLine 配置。装完后发消息触发一次渲染即可，老版本 Claude Code 需要完整重启才能识别 statusLine 变更。

两个环境相关的坑，提前说：

• Linux 报EXDEV: cross-device link not permitted：老版本 Claude Code 在/tmp是 tmpfs 时会撞到这个 bug。优先升级 Claude Code；升不了就用mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude启动后再装。
• Windows 提示没找到 JavaScript 运行时：先winget install OpenJS.NodeJS.LTS，重开终端再跑/claude-hud:setup。

不想进会话操作的话，也可以在终端里用 CLI 完成前两步：claude plugin marketplace add jarrodwatts/claude-hud加claude plugin install claude-hud@claude-hud。

HUD 每一行在告诉你什么

默认是两行，其余按关注点从高频到低频排：

[Opus] │ my-project git:(main*) Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)

上下文条：先看它，别的都可以不看

这是整个 HUD 里信息密度最高的一格。数据来自 Claude Code 原生的 token 统计，不是估算；上下文窗口多大（包括 1M 上下文的会话）都以 Claude Code 报告的值为准。颜色随占比从绿变黄再变红，占比到 85% 以上会展开 token 明细（display.showTokenBreakdown默认开）。如果你们团队的 auto-compact 阈值不是全窗口，可以把display.autoCompactWindow设成同一个数值，让 HUD 的百分比和/context对得上。

配额条：订阅用户才看得到

Usage ██░░░░░░░░ 25% (1h 30m / 5h)这一格显示 5 小时窗口和 7 天窗口的用量。前提是 Claude Code 在 stdin 里带了订阅用户的rate_limits数据，所以纯 API key 用户看不到这条，这是正常的。7 天用量超过 80%（display.sevenDayThreshold可调）才出现，避免平时刷屏。

工具行：确认它在干什么

◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2

◐是进行中，✓是已完成，×N是次数。这一行默认是关的，需要手动开display.showTools。它最大的用处是当 Claude 长时间"思考"时，你能确认它是在读文件还是在空转。

代理行：并行子任务的可观测性

◐ explore [haiku]: Finding auth code (2m 15s)

代理类型、模型标签、任务描述、已运行时长，一行给全。对应display.showAgents，默认也是关的。子代理跑几分钟是常态，没有这行你只能靠猜。

待办行与项目信息

▸ Fix authentication bug (2/5)

任务完成比例直接可见，对应display.showTodos。第一行里的项目路径、git 分支、脏标记*、领先/落后计数（↑2 ↓1）都是独立开关，jJujutsu 仓库也可以接管显示（jjStatus.enabled，默认关）。

值得动的配置项

日常调优跑/claude-hud:configure就行，它支持 Full（全开）、Essential（活动行+git）、Minimal（只有模型名和上下文条）三个预设，保存前能预览效果。配置文件在~/.claude/plugins/claude-hud/config.json，向导不认识的高级字段改完文件后会被保留。几个我个人建议优先设的：

另外两件事不在这个配置文件里，而是在~/.claude/settings.json的statusLine条目中：

• 加refreshInterval: 5（秒，最小 1）。Claude Code 只在交互后重绘状态栏，不加这个字段，会话时长和重置倒计时在两条消息之间会停摆。/claude-hud:setup安装时会问你。
• 临时不想看 HUD：CLAUDE_HUD_DISABLE=1 claude启动即可，不用去删 settings.json 里的配置。注意如果 shell profile 里 export 了这个变量，会连 setup 校验一起静默掉。

想改颜色、阈值这些细节，直接编辑 config.json 的colors.*和display.*，颜色支持色名（green、cyan等）、256 色编号和#rrggbb。

排错速查

• 配置不生效：JSON 语法错误会被静默回退到默认值，先检查格式；pathLevels只接受 1/2/3/full。
• 活动行（工具/代理/待办）不出现：除了开关没开，它们还要"有活动才渲染"，空转时不显示。
• git 分支不显示：确认当前目录在 git 仓库内、gitStatus.enabled不是false。
• 装了没显示：先发一条消息触发渲染；还不行就完整重启 Claude Code。

下一步建议

装完后按这个顺序收敛配置：先跑/claude-hud:configure选 Essential 预设保底；如果你经常并行开子代理，把display.showAgents和showTools打开；monorepo 用户把pathLevels调到 2；在 settings.json 里确认refreshInterval写上了。之后再按需开 cost、MCP/Skills 统计这类可选行，别一次全开——状态栏超过三四行会开始抢正文的视野。

想深入可以看仓库里的 中文文档、安装向导逻辑、配置向导逻辑 和 渲染模块源码，插件元信息在 .claude-plugin/plugin.json。

【免费下载链接】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