Claude Code 必装插件 – claude-hud:让你看清 AI 在干什么

上下文快满了？Claude 在读什么文件？子 Agent 跑了多久？现在你能看到了。

用 Claude Code 写代码，最烦的是什么？

你不知道它在干什么。

上下文快满了，等报错才知道。Claude 在后台读文件，你只能干等。子 Agent 跑了 5 分钟，不知道在干嘛。

Claude HUD 解决这个问题。终端底部实时显示：上下文使用率、工具调用、Agent 状态、任务进度。

安装

三条命令：

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

完成。无需重启，HUD 立即出现。

Linux 用户：如果遇到 EXDEV: cross-device link not permitted：

mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude

显示什么

第一行：基本信息

[Opus | Max] │ my-project git:(main*)

模型、订阅类型、项目路径、Git 分支。

第二行：资源使用

Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)

上下文条（绿→黄→红）+ Pro/Max 用户的速率限制。

第三行：工具活动

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

Claude 正在编辑什么文件，读了几次，搜了几次。

第四行：子 Agent

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

Agent 名称、模型、任务、运行时长。

第五行：Todo

▸ Fix authentication bug (2/5)

当前任务，完成进度。

三种模式

运行 /claude-hud:configure：

• • Full：显示所有信息
• • Essential：活动行 + Git，减少干扰
• • Minimal：只显示模型和上下文条

选完预设，还能单独开关每个元素。

配置

编辑 ~/.claude/plugins/claude-hud/config.json：

项目路径层级

{  "pathLevels": 2}

• • 1：my-project
• • 2：apps/my-project
• • 3：dev/apps/my-project

Git 详细信息

{  "gitStatus": {    "showDirty":true,        // * 表示未提交    "showAheadBehind":true,  // ↑2 ↓1    "showFileStats":true     // !3 +1 ?2  }}

符号：! 修改，+ 新增，✘ 删除，? 未跟踪。

上下文格式

{  "display": {    "contextValue": "percent"  // percent | tokens | remaining  }}

显示/隐藏

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

使用限制（Pro/Max/Team）

Pro/Max/Team 用户会看到速率限制：

Usage ██░░░░░░░░ 25% (1h 30m / 5h)

使用率 ≥ 80% 时显示 7 天限制：

Usage ██░░░░░░░░ 25% (1h 30m / 5h) | ██████████ 85% (2d / 7d)

API 用户按 token 付费，不显示限制。

技术原理

Claude Code → stdin JSON → claude-hud → stdout → 终端             ↘ transcript JSONL

• • 原生 token 数据（非估算）
• • 解析 transcript 获取活动
• • 每 300ms 更新

无需额外窗口，无需 tmux。

故障排查

配置不生效？

• • 检查 JSON 语法
• • pathLevels 必须是 1/2/3
• • 删除配置重新运行 /claude-hud:configure

Git 不显示？

• • 确认在 git 仓库中
• • 检查 gitStatus.enabled 不是 false

工具/Agent/Todo 不显示？

• • 默认隐藏，需要启用
• • 只在有活动时显示

使用限制不显示？

• • 用 Pro/Max/Team 账号登录（非 API key）
• • 检查 display.showUsage 不是 false

为什么用它

核心优势：

• • 用 Claude Code 官方 API
• • 300ms 刷新
• • 终端底部，不占空间
• • 三种预设 + 细粒度配置

开源

• • GitHub：https://github.com/jarrodwatts/claude-hud
• • 许可证：MIT

总结

Claude Code 很强，但不透明。Claude HUD 让你看清它在干什么。

三条命令装完，立即生效：

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

上下文、工具、Agent、进度，全在终端底部。