Claude HUD 状态栏无法启动问题排查记录

排查时间：2026-04-23 环境：Windows 11 Pro (win32), Git Bash, Node.js v24.14.1

---

一、问题描述

安装 claude-hud 插件后，状态栏始终无法显示。运行 /claude-hud:setup 命令时提示：

 Unknown command: /claude-hud:setup

即使插件已经成功安装（在 /plugin 界面中显示为 "Installed"），相关命令仍然不可用。

---

二、排查过程

第一步：检查插件是否正确安装

 # 检查 installed_plugins.json
 cat ~/.claude/plugins/installed_plugins.json

结果：

 {
   "version": 2,
   "plugins": {
     "claude-hud@claude-hud": [
       {
         "scope": "user",
         "installPath": "C:\\Users\\{USER}\\.claude\\plugins\\cache\\claude-hud\\claude-hud\\0.1.0",
         "version": "0.1.0",
         "installedAt": "2026-04-23T15:52:57.164Z"
       }
     ]
   }
 }

插件已注册，但发现问题：installPath 使用的是反斜杠 \（Windows 路径风格），而实际文件系统中插件位于：

 C:\Users\{USER}\.claude\plugins\cache\claude-hud\claude-hud\0.1.0\

---

第二步：检查插件缓存状态

错误信息：

 Failed to install: EBUSY: resource busy or locked, rm 'C:\Users\{USER}\.claude\plugins\cache\claude-hud'

原因：之前安装失败，导致缓存目录被锁定。

解决方案：

 rm -rf "/c/Users/{USER}/.claude/plugins/cache/claude-hud"

---

第三步：检查 statusLine 配置

读取 ~/.claude/settings.json 发现已有的 statusLine 配置：

 "statusLine": {
   "type": "command",
   "command": "node C:\\Users\\{USER}\\.claude\\plugins\\marketplaces\\jarrodwatts-claude-hud\\dist\\index.js"
 }

问题：这个路径是旧的/错误的路径：

• marketplaces/jarrodwatts-claude-hud ← 不存在

• 实际插件位置是 plugins/cache/claude-hud/claude-hud/0.1.0/

---

第四步：验证 Node.js 环境

 $ which node
 /d/Program Files/nodejs/node
 ​
 $ node --version
 v24.14.1

Node.js 已正确安装，路径为 /d/Program Files/nodejs/node。

---

第五步：测试正确的命令

使用正确的插件路径测试 HUD 启动：

cols=$(stty size </dev/tty 2>/dev/null | awk '{print }');
export COLUMNS=$(( ${cols:-120} > 4 ? ${cols:-120} - 4 : 1 ));
plugin_dir=$(ls -1d "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/*/claude-hud/*/ 2>/dev/null | sort -V | tail -1);
exec "/d/Program Files/nodejs/node" "${plugin_dir}dist/index.js"

输出：

[claude-hud] Initializing...

命令成功执行，HUD 正常初始化。

---

三、根本原因分析

原因 1：缓存锁定导致安装不完整

首次安装时因资源锁定失败，虽然 installed_plugins.json 中有注册，但实际文件可能不完整。

原因 2：statusLine 配置使用了硬编码的错误路径

旧配置中的路径 marketplaces/jarrodwatts-claude-hud 是插件市场的暂存路径，不是实际插件位置。

原因 3：插件命令需要重启才能加载

Claude Code 的插件系统需要在启动时加载插件命令。安装插件后，当前会话无法识别新命令，必须完全退出并重新启动。

---

四、解决方案

完整修复步骤

1. 清理旧缓存

rm -rf "/c/Users/{USER}/.claude/plugins/cache/claude-hud"

2. 重新安装插件

在 Claude Code 中运行：

/plugin install claude-hud

3. 完全退出 Claude Code（关键步骤！）

不仅仅是关闭窗口，必须完全退出进程。

4. 重新启动并运行设置向导

/claude-hud:setup

5. 再次重启 Claude Code

statusLine 配置写入后，需要再次重启才能生效。

---

五、正确的 statusLine 配置

Windows Git Bash 环境下的正确配置：

"statusLine": {
  "type": "command",
  "command": "cols=$(stty size </dev/tty 2>/dev/null | awk '{print }'); export COLUMNS=$(( ${cols:-120} > 4 ? ${cols:-120} - 4 : 1 )); plugin_dir=$(ls -1d \"${CLAUDE_CONFIG_DIR:-$HOME/.claude}\"/plugins/cache/*/claude-hud/*/ 2>/dev/null | sort -V | tail -1); exec \"/d/Program Files/nodejs/node\" \"${plugin_dir}dist/index.js\""
}

配置说明

组成部分	说明
cols=$(stty size </dev/tty ...)	获取终端宽度
export COLUMNS=...	设置列数，-4 是为了留出 Claude Code 输入区域的内边距
plugin_dir=$(ls -1d .../plugins/cache/*/claude-hud/*/)	动态查找最新版本的插件目录
sort -V	GNU 版本排序，确保 0.1.0 < 0.2.0
exec "/d/Program Files/nodejs/node" ...	使用 Node.js 执行插件

---

六、可选功能配置

创建 ~/.claude/plugins/claude-hud/config.json：

{
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showDuration": true,
    "showConfigCounts": true,
    "showSessionName": true
  }
}

功能	说明
showTools	显示工具活动 (◐ Edit: file.ts | ✓ Read ×3)
showAgents	显示子代理状态
showTodos	显示待办事项进度
showDuration	显示会话时长
showConfigCounts	显示配置计数 (CLAUDE.md, rules, MCPs)
showSessionName	显示会话名称

效果如图：

---

七、关键要点总结

1. 清理缓存：安装失败后必须清理 plugins/cache/claude-hud

2. 动态路径：使用 ls ... | sort -V | tail -1 动态查找插件目录，不要硬编码路径

3. 双重重启：插件安装后需要重启，statusLine 配置写入后也需要重启

4. Windows 路径格式：Git Bash 下使用 /d/Program Files/nodejs/node，而非 D:\Program Files\nodejs\node.exe

5. sort -V：Windows Git Bash 自带 GNU sort，支持 -V 版本排序选项

---

八、相关文件路径

文件	路径
settings.json	C:\Users\{USER}\.claude\settings.json
installed_plugins.json	C:\Users\{USER}\.claude\plugins\installed_plugins.json
插件缓存	C:\Users\{USER}\.claude\plugins\cache\claude-hud\claude-hud\0.1.0\
插件配置	C:\Users\{USER}\.claude\plugins\claude-hud\config.json

---

九、参考链接

• Claude HUD 插件：https://github.com/jarrodwatts/claude-hud

• Claude Code 插件文档