10分钟内部署claude-hud，实时监控Claude Code
claude-hud是一个Claude Code插件，提供实时监控，包括项目路径、上下文健康状况、工具活动、代理跟踪和待办事项进度。通过本教程，您将学会如何快速安装和配置claude-hud，提高您的开发效率。
1. claude-hud是什么，为什么需要它
claude-hud 是一个 Claude Code 插件，能够实时显示当前的项目路径、上下文健康状况、工具活动、代理跟踪以及待办事项进度。通过 claude-hud，我们可以更好地了解 Claude Code 会话中的情况，从而提高开发效率。
要使用 claude-hud，首先需要了解它的基本功能。claude-hud 通过 Claude Code 的原生 statusline API 来工作，不需要额外的窗口或 tmux 支持。它可以显示项目路径、上下文健康状况、工具活动、代理跟踪以及待办事项进度等信息。
claude-hud 的默认显示包括两个行：第一个行显示模型、提供商标签、项目路径和 git 分支；第二个行显示上下文条和使用率限制。我们还可以通过 /claude-hud:configure 命令来自定义 claude-hud 的显示，包括启用或禁用某些项、调整 git 显示样式、切换布局或改变标签语言。
在配置 claude-hud 时，我们可以选择预设（Full/Essential/Minimal），然后根据需要进行个性化设置。我们还可以通过编辑 ~/.claude/plugins/claude-hud/config.json 文件来进行高级设置，例如自定义颜色、阈值和显示格式。
本章小结
- claude-hud 是一个 Claude Code 插件，能够实时显示项目路径、上下文健康状况、工具活动、代理跟踪以及待办事项进度。
- claude-hud 通过 Claude Code 的原生 statusline API 来工作，不需要额外的窗口或 tmux 支持。
- 我们可以通过
/claude-hud:configure命令来自定义 claude-hud 的显示，包括启用或禁用某些项、调整 git 显示样式、切换布局或改变标签语言。
2. 安装claude-hud的步骤
要安装 claude-hud，我们需要按照几个步骤来操作。首先，确保你已经有一个 Claude Code 实例并且可以正常运行。
步骤 1：添加 marketplace
直接运行以下命令：
/plugin marketplace add jarrodwatts/claude-hud这条命令添加了 claude-hud 的 marketplace，预期结果是成功添加 marketplace。
步骤 2：安装 plugin
在 Linux 系统上，可能需要先设置 TMPDIR：
mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude然后在该 session 中运行：
/plugin install claude-hud预期结果是成功安装 claude-hud plugin。
步骤 3：重载 plugins
运行以下命令：
/reload-plugins预期结果是 plugins 被成功重载。
步骤 4：配置 statusline
运行以下命令：
/claude-hud:setup在 Windows 系统上，如果 setup 说没有找到 JavaScript runtime，需要先安装 Node.js：
winget install OpenJS.NodeJS.LTS然后重启 shell 并再次运行 /claude-hud:setup。
预期结果是成功配置 statusline，claude-hud 开始工作。
如果你遇到任何问题，记得检查命令是否正确输入，并且确保你的环境配置正确。
本章小结：
- 添加 claude-hud 的 marketplace
- 安装 claude-hud plugin
- 重载 plugins
- 配置 statusline 注意：在安装和配置过程中，可能会遇到特定系统的限制或问题，需要根据系统的提示进行调整。
3. 配置claude-hud的基本设置
配置claude-hud的基本设置，我们需要在安装并运行claude-hud后进行一系列的配置步骤。首先，确保你已经成功安装了claude-hud插件，并且已经运行了 /claude-hud:setup 命令。
步骤1：配置状态栏
直接运行以下命令：
/claude-hud:setup这步骤会配置claude-hud的基本设置，包括状态栏的显示。
步骤2：选择预设
在配置过程中，你会被提示选择一个预设（Preset）。有三个预设可供选择：Full、Essential和Minimal。每个预设显示的信息不同，你可以根据需要选择合适的预设。
# 选择Full预设
/claude-hud:configure --preset Full步骤3：自定义配置
如果你需要更详细的配置，可以运行以下命令：
/claude-hud:configure这会进入一个交互式的配置流程，你可以在这里调整HUD的布局、语言和其他设置。
步骤4：手动编辑配置文件
对于高级设置，你可以直接编辑配置文件。配置文件位于 ~/.claude/plugins/claude-hud/config.json。你可以在这里设置诸如颜色、路径级别、最大宽度等高级选项。
// 示例配置
{
"language": "zh-Hans",
"lineLayout": "expanded",
"pathLevels": 2,
"maxWidth": null,
"forceMaxWidth": false
}记住一点：配置文件的设置会被 /claude-hud:configure 命令覆盖，所以如果你需要保留手动设置的配置，最好直接编辑配置文件。
常见问题和排查
- 如果你在Windows上遇到“没有找到JavaScript运行时”的错误，需要安装Node.js LTS。
- 如果你在Linux上遇到“cross-device link not permitted”的错误，需要设置TMPDIR环境变量。
本章小结：
- 配置claude-hud的基本设置需要运行
/claude-hud:setup命令。 - 你可以选择预设（Full、Essential、Minimal）或自定义HUD的配置。
- 高级设置可以通过编辑
~/.claude/plugins/claude-hud/config.json文件来实现。 - 在配置过程中可能会遇到一些常见问题，需要根据错误提示进行相应的排查和解决。
4. 自定义claude-hud的高级设置
自定义claude-hud的高级设置
我们先来看看claude-hud的配置文件。 claude-hud的配置文件位于~/.claude/plugins/claude-hud/config.json，我们可以直接编辑这个文件来进行高级设置。
nano ~/.claude/plugins/claude-hud/config.json直接编辑配置文件可以设置诸如colors.*、pathLevels、maxWidth、阈值覆盖、display.timeFormat和display.promptCacheTtlSeconds等高级设置。
如果你想要使用guided配置流程，可以运行以下命令：
/claude-hud:configureguided配置流程可以让你选择布局、语言和常见的显示切换。高级设置会被保留，但你需要直接编辑配置文件来设置它们。
高级设置选项
| 选项 | 类型 | 默认值 | 描述 |
|---|---|---|---|
language |
en | zh | zh-Hans |
en |
HUD标签语言。英语是默认值；设置zh或zh-Hans以启用简体中文标签。 |
lineLayout |
string | expanded |
布局：expanded（多行）或compact（单行） |
pathLevels |
1-3 | 1 | 在项目路径中显示的目录级别 |
maxWidth |
number | null |
null |
可选的回退宽度，当终端宽度检测完全失败时使用 |
forceMaxWidth |
boolean | false | 即使终端宽度检测返回较小的值，也总是使用maxWidth |
记住一点：直接编辑配置文件可以设置高级选项，但guided配置流程会保留这些设置。
预设
| 预设 | 显示内容 |
|---|---|
| Full | 启用所有内容 —— 工具、代理、待办事项、Git、使用情况、持续时间 |
| Essential | 活动行 + Git状态，信息干扰最小 |
| Minimal | 核心内容 —— 只显示模型名称和上下文栏 |
选择预设后，你可以开启或关闭个别元素。
本章小结
- claude-hud的配置文件位于
~/.claude/plugins/claude-hud/config.json - 直接编辑配置文件可以设置高级选项，如
colors.*、pathLevels、maxWidth等 - guided配置流程可以选择布局、语言和常见的显示切换
- 高级设置会被保留，但需要直接编辑配置文件来设置它们
5. 使用claude-hud提高开发效率
使用claude-hud提高开发效率
我们先来看看claude-hud的基本功能。claude-hud是一个Claude Code插件，能够实时显示项目路径、上下文健康状况、工具活动、代理跟踪和待办事项进度等信息。这些信息可以帮助我们更好地了解项目的状态和进展。
配置claude-hud
在使用claude-hud之前，我们需要配置它。我们可以使用以下命令来配置claude-hud：
/claude-hud:configure这个命令会引导我们完成配置过程，我们可以选择预设的配置、语言和布局等。
预设配置
claude-hud提供了三个预设配置：Full、Essential和Minimal。我们可以根据自己的需要选择合适的预设配置。
- Full：显示所有信息，包括工具活动、代理跟踪和待办事项进度等。
- Essential：显示基本信息，包括项目路径、上下文健康状况和工具活动等。
- Minimal：只显示核心信息，包括模型名称和上下文栏等。
自定义配置
除了预设配置，我们还可以自定义claude-hud的配置。我们可以编辑~/.claude/plugins/claude-hud/config.json文件来修改配置。例如，我们可以修改语言、布局和显示的信息等。
使用claude-hud
配置好claude-hud后，我们可以开始使用它了。claude-hud会实时显示项目的状态和进展，我们可以根据这些信息来调整我们的开发工作。
例如，我们可以使用claude-hud来监控项目的上下文健康状况，当上下文健康状况不佳时，我们可以及时调整我们的开发工作以避免上下文溢出等问题。
提高开发效率
claude-hud可以帮助我们提高开发效率。通过实时监控项目的状态和进展，我们可以及时发现问题和瓶颈，并采取措施来解决它们。
例如，我们可以使用claude-hud来监控工具活动和代理跟踪，当工具活动和代理跟踪不正常时，我们可以及时调整我们的开发工作以避免工具和代理的冲突等问题。
小结
- claude-hud是一个Claude Code插件，能够实时显示项目路径、上下文健康状况、工具活动、代理跟踪和待办事项进度等信息。
- 我们可以配置claude-hud的预设配置、语言和布局等。
- claude-hud可以帮助我们提高开发效率，通过实时监控项目的状态和进展，我们可以及时发现问题和瓶颈，并采取措施来解决它们。
常见问题
问题：如何安装 Claude HUD？
安装 Claude HUD 需要在 Claude Code 实例中运行一系列命令。首先，添加 marketplace： /plugin marketplace add jarrodwatts/claude-hud，然后安装插件： /plugin install claude-hud，最后重载插件： /reload-plugins。如果你是 Linux 用户，可能需要设置 TMPDIR 以避免安装失败。
问题： Claude HUD 的配置选项有哪些？
Claude HUD 提供了多种配置选项，包括语言、布局、显示项目路径的目录级别、最大宽度等。这些配置可以通过 /claude-hud:configure 命令进行设置，也可以通过直接编辑 ~/.claude/plugins/claude-hud/config.json 文件来实现。
问题：如何更改 Claude HUD 的语言？
可以通过 /claude-hud:configure 命令来更改 Claude HUD 的语言。目前支持英语和简体中文两种语言。选择 中文 或设置 language 为 zh 或 zh-Hans 即可启用简体中文标签。
问题： Claude HUD 的布局可以自定义吗？
是的，Claude HUD 的布局可以自定义。通过 /claude-hud:configure 命令，可以选择 expanded（多行）或 compact（单行）布局。此外，还可以通过编辑 config.json 文件来设置自定义布局。
问题：如何解决 Linux 下安装 Claude HUD 失败的问题？
Linux 下安装 Claude HUD 失败可能是由于 /tmp 文件系统导致的。可以通过设置 TMPDIR 来解决这个问题： mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude，然后在该会话中运行安装命令。
问题： Claude HUD 与其他类似插件相比有什么优势？
Claude HUD 使用 Claude Code 的原生 statusline API，不需要单独的窗口或 tmux，能够在任何终端中工作。此外，它还提供了多种配置选项和自定义布局，能够根据用户的需求进行定制。
问题：如何更新 Claude HUD 的配置？
可以通过 /claude-hud:configure 命令来更新 Claude HUD 的配置。该命令提供了一个引导流程，能够帮助用户设置布局、语言和其他常见的显示选项。对于高级设置，可以直接编辑 ~/.claude/plugins/claude-hud/config.json 文件。
