Claude HUD插件完全指南：让你的Claude Code拥有实时监控仪表盘

💡 写在前面

你是否遇到过：使用Claude Code时不知道上下文用了多少？工具执行了什么？Agent在做什么？

别急，Claude HUD插件完美解决这个问题！本文详细介绍这款GitHub热榜插件的功能、安装和使用方法。

适合人群：Claude Code用户、AI开发者、效率工具爱好者

预计阅读时间：10-15 分钟

📋 内容大纲

Claude HUD是什么
核心功能详解
安装步骤
配置与自定义
常见问题解决
使用技巧

Claude HUD是什么

Claude HUD预览

Claude HUD是由 @jarrodwatts 开发的一款 Claude Code 插件，它会在你的终端底部显示一个实时监控仪表盘，让你随时了解：

✅ 上下文使用情况 - 避免超出token限制
✅ 活跃工具状态 - 实时查看文件读写操作
✅ 运行中的Agent - 监控子任务执行进度
✅ 待办事项进度 - 跟踪任务完成情况
✅ Git状态 - 显示分支和修改状态
✅ 使用量统计 - Pro/Max用户查看速率限制

为什么需要Claude HUD？

痛点	解决方案
不知道上下文用了多少	实时显示百分比进度条
看不到工具执行情况	显示读写文件、搜索等操作
Agent运行状态不透明	实时显示Agent名称和进度
待办事项完成情况不明	显示任务进度 (2/5)
频繁查看Git状态	直接显示分支和修改标记

核心功能详解

功能展示

1. 上下文健康监控

Context █████░░░░░ 45%

绿色 (0-60%)：安全范围
黄色 (60-85%)：注意范围
红色 (85%+)：警告范围

显示格式可选： - percent：45% - tokens：45k/200k - remaining：55% remaining

2. 工具活动追踪

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

实时显示Claude正在执行的操作： - ✓ Read：读取文件 - ◐ Edit：编辑文件 - ✓ Grep：搜索代码 - ✓ Bash：执行命令

3. Agent状态监控

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

显示正在运行的子Agent： - Agent名称和模型 - 当前执行的任务 - 运行时长

4. 待办事项进度

▸ Fix authentication bug (2/5)

当前任务名称
完成进度 (已完成/总数)

5. Git状态显示

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

可配置显示： - 分支名称 - 修改标记 (*) - 领先/落后远程 (↑2 ↓1) - 文件统计 (!3 +1 ?2)

6. 使用量监控（Pro/Max用户）

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

当前使用量百分比
已用时间 / 总限制
7天使用量（超过阈值时显示）

安装步骤

前提条件

Claude Code v1.0.80+
Node.js 18+ 或 Bun
Claude Pro/Max/Team 订阅（使用量显示需要）

安装命令

步骤1：添加插件市场

/plugin marketplace add jarrodwatts/claude-hud

步骤2：安装插件

/plugin install claude-hud

步骤3：配置状态栏

/claude-hud:setup

✅ 完成！ HUD立即显示，无需重启。

Linux用户特别注意

如果在Linux上遇到错误：

EXDEV: cross-device link not permitted

解决方法：

# 创建临时目录
mkdir -p ~/.cache/tmp

# 设置环境变量后启动Claude
TMPDIR=~/.cache/tmp claude

# 然后在会话中运行安装命令
/plugin install claude-hud

这是Claude Code平台的已知限制，详见 Issue #14799。

配置与自定义

配置界面

快速配置

运行配置向导：

/claude-hud:configure

预设模式：

预设	显示内容
Full	全部启用 - 工具、Agent、待办、Git、使用量
Essential	精简模式 - 活动行 + Git状态
Minimal	极简模式 - 仅模型名和上下文条

高级配置

编辑配置文件：

~/.claude/plugins/claude-hud/config.json

完整配置示例：

{
  "lineLayout": "expanded",
  "pathLevels": 2,
  "elementOrder": [
    "project",
    "tools",
    "context",
    "usage",
    "environment",
    "agents",
    "todos"
  ],
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": true
  },
  "display": {
    "showModel": true,
    "showContextBar": true,
    "contextValue": "percent",
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showUsage": true,
    "showDuration": true
  },
  "colors": {
    "context": "cyan",
    "usage": "cyan",
    "warning": "yellow",
    "usageWarning": "magenta",
    "critical": "red"
  }
}

配置项说明

选项	类型	默认值	说明
`lineLayout`	string	expanded	布局：expanded(多行) / compact(单行)
`pathLevels`	1-3	1	项目路径显示层级
`elementOrder`	array	[...]	元素显示顺序
`display.showTools`	boolean	false	显示工具活动行
`display.showAgents`	boolean	false	显示Agent状态行
`display.showTodos`	boolean	false	显示待办进度行

颜色配置

支持的颜色： - red, green, yellow - magenta, cyan - brightBlue, brightMagenta

常见问题解决

问题解决

问题1：配置不生效

现象：修改配置后HUD没有变化

解决方案：

# 1. 检查JSON语法
# 无效JSON会静默回退到默认配置

# 2. 确保值有效
# pathLevels 必须是 1, 2, 或 3
# lineLayout 必须是 "expanded" 或 "compact"

# 3. 删除配置重新生成
rm ~/.claude/plugins/claude-hud/config.json
/claude-hud:configure

问题2：Git状态不显示

现象：项目路径旁没有git分支信息

解决方案：

# 1. 确认在git仓库中
git status

# 2. 检查配置
gitStatus.enabled  # 确保不是 false

# 3. 重新配置
/claude-hud:configure

问题3：工具/Agent/待办行不显示

现象：这些行始终不出现

原因和解决方案：

默认隐藏：需要在配置中启用 json { "display": { "showTools": true, "showAgents": true, "showTodos": true } }
没有活动：只有有活动时才显示
Claude Code版本过低：升级到 v1.0.80+

问题4：使用量不显示

现象：Usage行不出现

可能原因：

原因	解决方案
不是Pro/Max/Team用户	需要订阅才能显示
使用API Key登录	需要使用OAuth登录
display.showUsage为false	设置为true
使用AWS Bedrock	Bedrock模式隐藏使用量
代理问题	设置HTTPS_PROXY环境变量

检查登录方式：

# 确保是OAuth登录，不是API Key
cat ~/.claude/auth.json | grep "oauth"

问题5：Linux安装失败

错误：EXDEV: cross-device link not permitted

解决方案：

# 方法1：设置TMPDIR
mkdir -p ~/.cache/tmp
TMPDIR=~/.cache/tmp claude

# 方法2：使用--tmp-dir参数
claude --tmp-dir ~/.cache/tmp

使用技巧

技巧1：监控上下文避免超限

场景：处理大型代码库时容易超出token限制

方法： - 关注Context进度条颜色 - 黄色时开始考虑清理上下文 - 红色时立即使用 /clear 或 /compact

技巧2：跟踪Agent执行

场景：启动多个Agent后不知道哪个在运行

方法： - 启用 showAgents - 查看Agent名称和运行时长 - 长时间运行的Agent可能需要检查

技巧3：监控工具使用

场景：想知道Claude具体在做什么

方法： - 启用 showTools - 观察Read/Edit/Grep操作 - 发现不必要的文件访问时优化提示词

技巧4：Git状态一目了然

场景：频繁切换分支，忘记当前状态

配置推荐：

{
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": false
  }
}

技巧5：自定义颜色主题

暗色终端推荐配置：

{
  "colors": {
    "context": "cyan",
    "usage": "brightBlue",
    "warning": "yellow",
    "usageWarning": "magenta",
    "critical": "red"
  }
}

📚 相关文章推荐

你可能还想看：

📢 关注「Geek 运维」

了解更多最新 Geek 技术分享！

关注 Geek 运维公众号

长按识别图中二维码，关注「Geek 运维」公众号，获取：

最新 AI 工具资讯
Claude Code 使用技巧
开发效率提升指南
开源工具推荐

📚 往期回顾

💬 互动时间

你用过Claude HUD吗？

使用体验如何？
有什么配置技巧？
欢迎在评论区留言讨论！

🎁 福利

关注「Geek 运维」公众号，回复 "ClaudeHUD" 获取：

配置文件模板合集
颜色主题方案
常见问题速查表
插件推荐清单

❓ 常见问题

Q1: Claude HUD支持Windows吗？ A: 支持，只要运行Claude Code的终端都支持。

Q2: 免费版Claude能用吗？ A: 可以，但使用量显示功能需要Pro/Max/Team订阅。

Q3: 如何卸载插件？ A: 运行 /plugin uninstall claude-hud

Q4: 更新插件后配置会丢失吗？ A: 不会，配置会保留。

Q5: 支持自定义布局吗？ A: 支持，通过修改config.json可以调整元素顺序和显示/隐藏。

本文基于Claude HUD v1.0官方文档整理 GitHub: https://github.com/jarrodwatts/claude-hud 最后更新：2026年3月19日

Claude HUD插件完全指南：让你的Claude Code拥有实时监控仪表盘

Claude HUD插件完全指南：让你的Claude Code拥有实时监控仪表盘

📋 内容大纲

Claude HUD是什么

核心功能详解

1. 上下文健康监控

2. 工具活动追踪

3. Agent状态监控

4. 待办事项进度

5. Git状态显示

6. 使用量监控（Pro/Max用户）

安装步骤

前提条件

安装命令

Linux用户特别注意

配置与自定义

快速配置

高级配置

配置项说明

颜色配置

常见问题解决

问题1：配置不生效

问题2：Git状态不显示

问题3：工具/Agent/待办行不显示

问题4：使用量不显示

问题5：Linux安装失败

使用技巧

技巧1：监控上下文避免超限

技巧2：跟踪Agent执行

技巧3：监控工具使用

技巧4：Git状态一目了然

技巧5：自定义颜色主题

📚 相关文章推荐

📢 关注「Geek 运维」

📚 往期回顾

💬 互动时间

🎁 福利

❓ 常见问题

评论区