# Claude HUD：给 Claude Code 装上一条真正有用的状态栏

我平时用 Claude Code，会话一长，最容易冒出来的问题其实都和“状态不够直观”有关：

- 会话上下文用了多少，只能靠体感猜
- Claude 现在是在读文件、改文件，还是已经把任务交给子代理，不够直观
- Todo 走到哪一步了，不打开 transcript 很难一眼看清

最近我把 `jarrodwatts/claude-hud` 这个项目从 README 一路读到 `commands/setup.md` 和源码。最开始我以为它只是一个终端美化插件，读完之后感觉不太一样：它不是来“装饰” Claude Code 的，而是在补那层平时最缺的运行时可见性。

截至 2026 年 3 月 28 日，这个仓库在 GitHub 上大约有 14.5k Stars、591 Forks。它不是一个独立终端应用，也不是 tmux 主题，而是一个 Claude Code 插件：直接挂在 statusline API 上，把上下文、工具、agent、todo、git 状态都压到你输入框下面。

## 项目定位与默认显示

README 里有一句话，基本把这个项目说清了：“Real-time statusline HUD for Claude Code”。

这里真正要看的是 `statusline`。

它没有再造一个 UI，也没有要求你另外开一个面板。它做的事情很直接：

- 继续使用 Claude Code 自己的 statusline 能力
- 从 Claude Code stdin 里拿官方数据
- 再结合 transcript JSONL、本地配置和 git 状态
- 最后在终端下方输出多行状态信息

项目的思路很直接：不是另外造一个界面，而是把 Claude Code 本来就有的数据，整理成一条更适合长期使用的状态栏。

你真正能看到的东西，按 README 和源码，大概分成几类：

- 当前模型名，比如 `Opus`、`Sonnet`
- 项目路径和 git 分支
- 当前上下文占用百分比
- 订阅用户的 5 小时 / 7 天 usage
- 正在运行的工具
- 正在跑的 subagent
- 当前 todo 进度

这里很容易看错：默认并不是所有东西都会显示。

按 README 现在的默认行为，真正默认常驻的是两行：

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

而工具、agent、todo 这些行，默认是关闭的，要通过 `/claude-hud:configure` 再开启。

这一点处理得比较克制。作者没有上来就把所有状态都塞满，而是先把最常看的两行做好，活动信息留给后面按需打开。

![claude-hud-default-vs-optional.png](https://developer.qcloudimg.com/http-save/yehe-7136204/b45734f28a49d80e1663f9a7abda2492.png)

## 安装与最小验证

如果你准备自己试一下，前提其实很简单。Claude HUD 不是独立应用，它要求你本机已经有可用的 Claude Code。README 和 `CLAUDE.README.md` 里给出的前提是：

- `Claude Code v1.0.80+`
- 本机有 JavaScript runtime，最稳的是 `Node.js 18+`，也可以用 Bun

如果你已经在用 Claude Code，Claude HUD 的安装路径非常短：

```text
/plugin marketplace add jarrodwatts/claude-hud
/plugin install claude-hud
/claude-hud:setup
```

然后重启 Claude Code，让新的 `statusLine` 配置生效。

不过装之前最好先记住两个细节，不然很容易装完了却不知道问题出在哪。

- `/claude-hud:setup` 负责把 `statusLine` 写进 `~/.claude/settings.json`
- 更细的 HUD 配置则放在 `~/.claude/plugins/claude-hud/config.json`

前者解决“HUD 有没有真正挂上去”，后者解决“这条 HUD 怎么显示”。

装完之后，最有用的一条命令其实是：

```text
/claude-hud:configure
```

因为默认 HUD 只开核心两行。tools、agents、todos 这些更有现场感的行，还是要靠 `configure` 去切布局、选 preset，或者手动打开。

![claude-hud-install-path.png](https://developer.qcloudimg.com/http-save/yehe-7136204/05afab4ff198c9131ef91b620070275a.png)

如果 `setup` 真正成功，且你已经完整重启 Claude Code，那么界面上应该会出现一条实际挂进去的 HUD。下面这张图比较有代表性，因为它不是示意图，而是真正装好之后的现场状态：

![claude-hud-setup-success.png](https://developer.qcloudimg.com/http-save/yehe-7136204/0f978d54a35b16b6e14676a3d3b2964a.png)

反过来说，如果你装完之后什么都没出现，最先要查的不是主题，而是 `~/.claude/settings.json` 里到底有没有写入 `statusLine`。没有这项配置，就说明 HUD 根本还没真正挂上去。

再往下，最需要提前说清楚的坑主要是两个，而且都不是小概率问题。

### Linux 下的 EXDEV 限制

`commands/setup.md` 里专门写了一段 Linux 的 cross-device filesystem 检查。

问题背景是：很多 Linux 机器的 `/tmp` 和 home 目录不在同一个文件系统上，这会导致 Claude Code 插件安装阶段报：

```text
EXDEV: cross-device link not permitted
```

作者给的 workaround 也很直接：

```bash
mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude /plugin install claude-hud
```

这不是 Claude HUD 自己发明的问题，而是 Claude Code 插件安装在 Linux 上会碰到的已知限制。作者把它提前写进 setup 流程里，这一点很实用，因为它省掉了很多“为什么我明明照着装却不行”的无效排查。

### Windows 上的 runtime 要求

README 也写了另一个常见问题：Windows 上如果 `/claude-hud:setup` 报找不到 JavaScript runtime，最简单的修法是先装 Node.js LTS，再重开 shell。

所以 Claude HUD 虽然是 Claude Code 插件，运行本体还是 Node/Bun 这套 JavaScript runtime。这一点不提前知道，Windows 上会很容易以为是插件本身坏了。

这跟它的 `package.json` 是对得上的：

- `type: module`
- `main: dist/index.js`
- `engines.node >= 18`

如果你只想做最小验证，我建议按这个顺序：

1. 在 Claude Code 里完成安装和 setup
2. 重启 Claude Code
3. 先确认默认两行 HUD 已经出现
4. 再跑一次 `/claude-hud:configure`
5. 打开 tools / agents / todos 其中一两项，观察状态栏是否随会话变化

按这条顺序走，比较容易确认：你看到的不是静态装饰，而是真的接进了会话过程。

如果你是 API-key-only 用户，或者跑的是 AWS Bedrock，README 也明确写了 usage 行可能不会出现。这不是 HUD 失效，而是 Claude Code 没有在 stdin 里提供适用的 subscriber `rate_limits` 数据。

## 状态栏的数据来源

看这类状态栏项目，最先要看的是取数方式。如果上下文和状态主要靠插件自己猜，结果通常不太稳定。Claude HUD 这里相对克制。

从 `src/index.ts`、`src/stdin.ts` 和 `CLAUDE.md` 可以看出，它的数据主要来自 4 个地方：

![claude-hud-data-flow.png](https://developer.qcloudimg.com/http-save/yehe-7136204/1f92bfaf0f8130c368bf4f15f766c795.png)

### 1. Claude Code 通过 stdin 送进来的原生数据

比如：

- `model.display_name`
- `context_window.current_usage`
- `context_window.context_window_size`
- `rate_limits`
- `transcript_path`
- `cwd`

尤其上下文占用这件事，作者专门在 `stdin.ts` 里优先用 Claude Code 原生提供的 `used_percentage`。

只有拿不到原生百分比时，才回退到手动计算。

这意味着新版 Claude Code 下，HUD 的 context 百分比会尽量和官方 `/context` 对齐，而不是自己算一套近似值。

### 2. transcript JSONL

第二个关键来源是 transcript。这部分值得多看一眼，因为 tools、agents、todos 这些东西到底靠不靠谱，基本就看它这里怎么取数。

`src/transcript.ts` 做的事情很明确：

- 解析 session transcript JSONL
- 把 `tool_use` 和 `tool_result` 对起来
- 抽出正在运行或已完成的工具
- 从 `Task` 调用里识别 agent
- 从 `TodoWrite` 里拿 todo 列表
- 记录 session 开始时间和 session 名称

这也是为什么它能显示：

- 当前哪些工具在跑
- 某个 agent 正在干什么
- todo 现在是几项完成、几项进行中

换句话说，Claude HUD 不是“自己知道 Claude 在做什么”，而是把 Claude Code 已经留下的 transcript 重新解释成一条可读状态线。

还有一个很值得写出来的实现细节：

`CLAUDE.md` 明确提到 Claude Code 大约每 300ms 会调用一次状态栏。如果每次都全量重读 transcript，这个插件很容易把自己拖慢。`src/transcript.ts` 的处理办法是按 transcript 路径生成 cache 文件，再用文件的 `mtime` 和 `size` 判断缓存是否有效。

它不是每次都暴力重扫整个 JSONL，而是在高频调用和会话可见性之间做了一个比较扎实的折中。

### 3. 本地 Claude 配置

`src/config-reader.ts` 会去数这些东西：

- `CLAUDE.md`
- rules
- MCP servers
- hooks

所以你在 HUD 里看到的 config counts，不是写死的提示词，而是从用户级和项目级配置里实时数出来的。

这也是 Claude HUD 和普通“上下文条”不一样的地方：它不只盯当前会话，还会把你项目里的 Claude 配置环境带进来。对已经开始用 `CLAUDE.md`、rules、MCP、hooks 的人来说，这一点会很有感觉。

### 4. git 和机器运行环境

`src/git.ts` 会拿：

- branch
- dirty 状态
- ahead / behind
- file stats

`src/memory.ts` 和 `src/speed-tracker.ts` 则补了：

- 系统内存占用
- output token speed

但这两个默认都不是强开项，尤其 memory usage 明确是 opt-in。

作者对默认项和可选项分得比较清楚，不会把所有指标都一股脑塞出来。

## 状态栏的渲染与布局

源码里还有一层比较关键的实现：它没有把这些信息硬拼成一行，而是做了一套清晰的分层渲染：

- `render/index.ts` 负责总协调
- identity / project / environment / usage / memory 这些基础行分开渲染
- tools / agents / todos 这些活动行也独立处理
- 再根据 `lineLayout`、terminal width、颜色配置决定怎么拼

另外一个容易被忽略的点，是它认真处理了终端显示的细节：

`render/index.ts` 里专门在做这些事：

- ANSI 颜色转义的保留与裁切
- grapheme 分段
- 宽字符宽度处理
- 按终端宽度截断

这些听起来像实现细节，但恰恰决定了它是不是能长期用。终端里最烦的通常不是“没功能”，而是：

- 中文一混进来就错位
- emoji 或宽字符把布局撑歪
- 颜色一截断就变成乱码

Claude HUD 在这层下了工夫，所以它更像一个认真维护的终端 UI 工具，而不是一个周末 demo。

## 适合的使用场景

下面这几类人会更容易用到它：

- 你每天都在用 Claude Code，而且一开就是长会话
- 你会开 subagent、会写 todo，希望过程别再全靠猜
- 你已经在项目里用 `CLAUDE.md`、rules、MCP、hooks，想更直观地知道环境在变复杂
- 你已经受够了“上下文快满了没感觉”“Claude 到底是在跑工具还是停住了”这种状态不透明

尤其是已经开始把 Claude Code 用深的人，感受会更明显。它补的不是视觉效果，而是那层平时最缺的运行时透明度。

## 能力边界

如果你期待的是下面这些东西，那就需要先把边界看清楚：

- 不替代 Claude Code 主界面
- 不提供独立 dashboard
- 不做任务编排
- 不做记忆管理
- 不改变 Claude 的能力边界

它本质上还是一条 statusline。

换句话说，如果你要的是：

- 一个完整的 agent 控制台
- 类似 OpenClaw / ClawTeam 那种团队协同层
- 或者一个能回放所有动作的独立监控面板

那 Claude HUD 就不是那个方向。

它更像一种很具体的小工具：不大，不抢戏，但很容易每天都用上。

它做的事情很朴素，就是把 Claude Code 当前这几秒到底在发生什么，尽量用一眼能扫完的方式告诉你。

对 Claude Code 的重度用户来说，这类工具的价值其实很现实：它不会改变 Claude Code 的能力上限，但会明显改善判断会话状态的速度。context 快满了没有、现在到底在跑工具还是子代理、todo 到哪一步了，这些信息一旦能低成本看见，整段使用体验会稳很多。

## 仓库信息

项目名：jarrodwatts/claude-hud。

如果准备自己试，先看 README.md、commands/setup.md 和 commands/configure.md，这三份基本就能把安装、setup 和显示项配置跑通。

如果想看实现，顺着 src/index.ts、src/stdin.ts、src/transcript.ts、src/render/index.ts、CLAUDE.md 这条线读，差不多就能把取数、解析 transcript 和渲染流程串起来。

如果这篇文章对你有帮助，欢迎点个赞、点个在看，也欢迎关注。

后面还会继续写 Claude Code、Codex、OpenClaw 这些项目的实测和使用笔记。

我平时用 Claude Code，会话一长，最容易冒出来的问题其实都和“状态不够直观”有关：

Claude HUD：给 Claude Code 装上一条真正有用的状态栏

软件研发

开发工具

前端

ClaudeHUD是专为ClaudeCode设计的实时状态栏插件，可直观显示上下文占用、工具运行、子代理状态和任务进度。安装简单，支持自定义显示项，有效解决长会话状态不透明问题。适合ClaudeCode深度用户提升工作效率，GitHub已获14.5k星。

文件系统

Windows

GitHub

Linux

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Claude HUD：给 Claude Code 装上一条真正有用的状态栏-腾讯云开发者社区-腾讯云

Claude HUD：给 Claude Code 装上一条真正有用的状态栏

Claude HUD：给 Claude Code 装上一条真正有用的状态栏

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐