跳转到内容
全部开发指南

Claude Code 上下文快满了却不知道？用 Claude HUD 加一条实时状态栏

AIGoCode发布于 更新于

Claude Code 上下文快满了却不知道？用 Claude HUD 加一条实时状态栏 封面

用 Claude Code 最怕的不是写错代码，改改就好；最怕的是写着写着质量突然下滑：前面说好的逻辑它不认了，该记住的上下文全忘了。等你反应过来，上下文已经满了。

问题在于，Claude Code 默认不会把上下文用量摆在你眼前，往往要等到感觉不对劲才发现。Claude HUD 是一个开源的 Claude Code 插件，它在终端底部加一条状态栏，实时显示上下文占用、正在调用的工具、子 Agent 进度和 TODO 进度。

本文适合经常跑长会话、想知道 Claude Code 此刻在干什么的开发者。下面讲 Claude HUD 显示什么、怎么安装、上下文进度条怎么看、能自定义哪些内容，以及它的工作原理。

Claude HUD 原文配图 1

Claude HUD 显示什么

装好后，终端底部会多出几行信息，大致是这样：

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

◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2
◐ explore [haiku]: Finding auth code (2m 15s)
▸ Fix authentication bug (2/5)

一眼能看到五类信息：

  • 当前模型：Opus 还是 Sonnet；
  • 上下文健康度：进度条从绿到黄到红，45% 还是 85% 不用猜；
  • 工具动态：正在编辑哪个文件、读了几个文件、搜索了几次；
  • 子 Agent 状态：哪个子 Agent 在跑、跑了多久、在做什么；
  • TODO 进度：当前任务做到第几步。

不需要额外窗口，也不需要 tmux，就显示在输入框下方。工具、子 Agent、TODO 这几行在新版本里是可选项，可以按需打开。

Claude HUD 原文配图 2

安装 Claude HUD

在 Claude Code 里依次输入：

# 1. 添加插件市场
/plugin marketplace add jarrodwatts/claude-hud

# 2. 安装
/plugin install claude-hud

# 3. 配置状态栏
/claude-hud:setup

官方 README 目前的说明是：执行 setup 后 Claude Code 会自动重新加载设置，状态栏马上出现，不必再重启。习惯在终端操作的话，也可以用：

claude plugin marketplace add jarrodwatts/claude-hud
claude plugin install claude-hud@claude-hud

然后在会话里执行 /reload-plugins 和 /claude-hud:setup。

原文提到配置时可以选 Full、Essential、Minimal 三种预设，分别对应全部信息、活动状态加 Git、只显示模型名和上下文进度条。新版本改为通过 /claude-hud:configure 按项开关，具体选项以你安装的版本为准。

Claude HUD 原文配图 3

常见安装问题

  • Linux 报 EXDEV: cross-device link not permitted：原文给出的原因是 /tmp 在单独的文件系统上，解决办法是换一个临时目录启动 Claude Code 后重新安装：
mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude
  • Windows 提示找不到 JavaScript 运行时：官方建议安装 Node.js LTS（winget install OpenJS.NodeJS.LTS），重启终端后再执行 /claude-hud:setup；
  • 状态栏不出现：先发一条消息，状态栏在交互之后才渲染；如果 Node 或 Bun 路径变了（比如升级了 nvm），重新执行一次 setup。

上下文进度条怎么看

其他信息是锦上添花，上下文进度条才是这个插件的核心。Claude Code 成本失控，根源常常在上下文管理：不知道用了多少，就没法判断该继续写、手动压缩，还是开新会话。

这条进度条读取的是 Claude Code 原生上报的上下文数据，不是外部估算，并会跟随实际窗口大小调整，原文提到也支持 100 万 token 的会话。

  • 绿色：余量充足；
  • 黄色：开始紧张，注意控制；
  • 红色：快满了，考虑压缩或开新会话。

原文还提到，占用超过 85% 时会自动展开 token 明细：输入多少、输出多少、缓存命中多少，能看清钱花在了哪。想进一步核对一次任务的实际消耗，可以对照账户侧的用量记录一起看。

Claude HUD 原文配图 4

能自定义哪些内容

配置文件在 ~/.claude/plugins/claude-hud/config.json（设置了 $CLAUDE_CONFIG_DIR 时在对应目录下），无效值会回退为默认值。

显示内容：

  • 上下文显示格式：百分比、具体 token 数、剩余比例，或全部显示；
  • 是否显示 Git 分支、未提交文件数、与远程的差距；
  • 是否显示会话时长、输出速度（tok/s）、系统内存占用；
  • 是否显示 Claude Code 版本号。

视觉定制：进度条颜色支持 256 色和十六进制色值；布局可选多行展开或单行紧凑；各模块顺序可以自己排。

改完执行 /claude-hud:configure 即可生效，之前手动改过的高级设置会保留。

Claude HUD 的工作原理

Claude Code → 输出 JSON → claude-hud 解析 → 渲染到终端状态栏
           ↘ transcript JSONL（工具、Agent、TODO 记录）

Claude HUD 本质上是一个 Claude Code 的 status line 命令，用的是官方的 statusline 机制，不是 hack。Claude Code 把会话数据（模型、上下文窗口、费用、限流、提示缓存等）通过标准输入传给它，它格式化后显示；工具、子 Agent、TODO 这几行则额外读取会话记录文件。

官方 README 写明它只在本地运行：不发网络请求、不读取凭据、不调用未公开的 API，唯一的写入是插件目录下记录输出速度和费用的小状态文件。

和 Everything Claude Code 搭配

Everything Claude Code（ECC）解决的是“调教” Claude Code 的能力：记忆、学习、子 Agent 编排；Claude HUD 解决的是可观测性。打个比方，ECC 是给赛车换发动机和轮胎，Claude HUD 是给驾驶位装仪表盘。如果你在考虑装 ECC，可以先看看一次装进大量 skill 对上下文的影响，再配合 HUD 观察上下文变化。

Claude HUD 原文配图 5

总结

AI 编程工具的能力已经不是主要瓶颈，真正影响效率的常常是信息差：上下文悄悄满了你没察觉，子 Agent 跑偏了没看见，token 烧了多少心里没数。Claude HUD 把这些信息放到输入框下方，让你随时判断是继续推进、压缩上下文，还是开新会话。

如果你还没开通 Claude Code，可以在 AIGoCode 上直接接入，装好 Claude HUD 后从第一个会话就能看清用量。

参考链接