Claude HUD：让 Claude Code 的内心活动一目了然
一个 Claude Code 插件，实时显示上下文使用率、工具活动、Agent 状态和任务进度。
它是什么
Claude HUD 是一个 Claude Code 插件，在终端输入框下方常驻显示状态信息。不需要额外窗口，不需要 tmux，任何终端都能用。
核心功能：
- 📊 上下文健康度 — 精确显示上下文窗口使用率，避免突然超限
- 🔧 工具活动 — 实时查看 Claude 读取、编辑、搜索文件的操作
- 🤖 Agent 追踪 — 显示正在运行的子 Agent 及其任务
- ✅ Todo 进度 — 跟踪任务完成状态
- 📁 项目路径 — 显示当前工作目录和 Git 分支
- ⏱️ 用量统计 — Claude 订阅用户的速率限制消耗情况
安装步骤
Step 1: 添加市场源
/plugin marketplace add jarrodwatts/claude-hud
Step 2: 安装插件
/plugin install claude-hud
⚠️ Linux 用户注意：如果安装失败提示 EXDEV: cross-device link not permitted，是因为 /tmp 是独立文件系统。解决方法：
mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude
然后在这个会话中运行安装命令。
⚠️ Windows 用户注意：如果 setup 提示找不到 JavaScript 运行时，先安装 Node.js LTS：
winget install OpenJS.NodeJS.LTS
Step 3: 配置状态线
/claude-hud:setup
完成后重启 Claude Code，HUD 就会显示。
显示效果示例
[Opus] │ my-project git:(main*) Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h) - Line 1 — 模型、项目路径、Git 分支 - Line 2 — 上下文条（绿→黄→红）和用量限制 ◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2 ← 工具活动 ◐ explore [haiku]: Finding auth code (2m 15s) ← Agent 状态 ▸ Fix authentication bug (2/5) ← Todo 进度
配置选项
运行 /claude-hud:configure 进入引导式配置流程。
预设模式
| 预设 | 显示内容 |
|---|---|
| Full | 全部启用 — 工具、Agent、Todo、Git、用量、时长 |
| Essential | 活动行 + Git 状态，最小化信息干扰 |
| Minimal | 核心仅显示 — 模型名称和上下文条 |
高级配置
编辑 ~/.claude/plugins/claude-hud/config.json：
{
"lineLayout": "expanded",
"pathLevels": 2,
"gitStatus": {
"enabled": true,
"showDirty": true,
"showAheadBehind": false,
"showFileStats": false
},
"display": {
"showTools": true,
"showAgents": true,
"showTodos": true,
"showDuration": true,
"showUsage": true
},
"colors": {
"context": "green",
"usage": "brightBlue",
"warning": "yellow",
"critical": "red"
}
}
常用配置项
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
lineLayout | string | expanded | 布局：expanded（多行）或 compact（单行） |
pathLevels | 1-3 | 1 | 项目路径显示的目录层级 |
display.showTools | boolean | false | 显示工具活动行 |
display.showAgents | boolean | false | 显示 Agent 活动行 |
display.showTodos | boolean | false | 显示 Todo 进度行 |
display.showUsage | boolean | true | 显示 Claude 订阅用量限制 |
display.showDuration | boolean | false | 显示会话时长 |
技术原理
Claude HUD 使用 Claude Code 的原生 statusline API：
Claude Code → stdin JSON → claude-hud → stdout → 终端显示
↘ transcript JSONL (工具、Agent、Todo)
- 从 Claude Code 获取原生 Token 数据（非估算）
- 适配 Claude Code 报告的上下文窗口大小（包括 1M 上下文会话）
- 解析 transcript 获取工具/Agent 活动
- 约 300ms 更新一次
常见问题
HUD 不显示？
- 重启 Claude Code 以加载新的 statusLine 配置
- macOS 用户需完全退出后重新运行
claude
Git 状态缺失？
- 确认在 Git 仓库内
- 检查
gitStatus.enabled未设为false
工具/Agent/Todo 行不显示？
- 这些默认隐藏，需在 config 中启用
showTools、showAgents、showTodos - 仅在有活动时会显示
用量不显示？
- 需使用 Claude 订阅账号登录（非 API Key 用户）
- AWS Bedrock 模型不显示用量限制
- 首次会话可能在第一个模型响应后才显示
系统要求
- Claude Code v1.0.80+
- Node.js 18+ 或 Bun
开发
git clone https://github.com/jarrodwatts/claude-hud cd claude-hud npm ci && npm run build npm test
许可证： MIT