Claude Code 安装 Claude HUD 尝试

Claude Code 安装 Claude HUD 完整指南

Claude HUD 是目前最受欢迎的 Claude Code 插件（22k+ stars），可在终端底部实时显示 context 用量、工具活动、Agent 状态和 Todo 进度，让你对 AI 编码会话一目了然。

什么是 Claude HUD？

Claude HUD 使用 Claude Code 原生的 statusline API，无需独立窗口，不依赖 tmux，在任何终端中均可工作。

安装后效果如下：

[Opus] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)
◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2
◐ explore [haiku]: Finding auth code (2m 15s)
▸ Fix authentication bug (2/5)

显示内容包括：

Line 1：当前模型、项目路径、git 分支
Line 2：Context 进度条（绿→黄→红）+ 用量限制
工具活动：正在执行的 Edit / Read / Grep 等操作
Agent 状态：子 Agent 名称、任务描述、耗时
Todo 进度：当前任务完成进度

前置要求

依赖	说明
Claude Code	已安装并可正常使用
Node.js LTS	v18 或更高版本

安装 Node.js（macOS）

运行 /claude-hud:setup 时如果提示需要安装 Node.js，推荐用 Homebrew 安装：

方式一：Homebrew（推荐）

# 如果还没有 Homebrew，先安装：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Node.js LTS
brew install node

方式二：官网安装包

前往 https://nodejs.org 下载 LTS 版本，双击 .pkg 安装即可。

安装完成后，重启终端让 PATH 生效，然后验证：

node --version
# 输出类似 v20.x.x 即可

安装步骤

第一步：添加插件市场并安装

在 Claude Code 中依次运行：

/plugin marketplace add jarrodwatts/claude-hud

/plugin install claude-hud@claude-hud

第二步：运行配置向导

/claude-hud:setup

💡 如果刚安装完 Node.js，需要先重启终端让 PATH 生效，再重新进入 Claude Code 运行此命令。

如果提示 Unknown command，先执行：

/reload-plugins

再重试 /claude-hud:setup。

向导会引导你选择：

预设布局：Full / Essential / Minimal
显示语言：English / 中文

第三步：完全重启 Claude Code

完全退出（不只是关闭终端 tab），再重新运行 claude。

⚠️ 新的 statusLine 配置只在启动时加载，必须完整重启才生效。

重启后 HUD 会出现在终端底部。

手动配置（备用方案）

如果 /claude-hud:setup 无法运行，可以手动编辑配置。

第一步：查看插件实际安装路径

ls ~/.claude/plugins/cache/*/claude-hud/

第二步：编辑 ~/.claude/settings.json，加入：

{
  "statusLine": {
    "type": "command",
    "command": "node ~/.claude/plugins/cache/claude-hud/claude-hud/<版本号>/dist/index.js"
  }
}

将 <版本号> 替换为上一步查到的实际路径（如 0.0.9）。

第三步：完全重启 Claude Code。

常见问题

Unknown command: /claude-hud:setup

插件已安装但未加载，执行：

/reload-plugins

再重试 /claude-hud:setup。

Linux 安装报错（跨文件系统移动失败）

Linux 的 /tmp 通常挂载为独立 tmpfs，导致文件移动失败。解决方法：

mkdir -p ~/tmp
TMPDIR=~/tmp claude

Windows 上 HUD 频繁闪烁黑窗口

这是已知 Bug，PowerShell 每次刷新 statusLine 时会生成可见的控制台窗口。
临时解法：手动修改 settings.json 中的 command 字段，避免用 powershell -Command "..." 包裹，或等待官方修复。

重启后 HUD 消失（Windows 11）

检查插件状态：

CLAUDE_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
ls "$CLAUDE_DIR/plugins/cache"/*/claude-hud 2>/dev/null && echo "Cache OK" || echo "Cache missing"
grep -q "claude-hud" "$CLAUDE_DIR/plugins/installed_plugins.json" && echo "Registry OK" || echo "Registry missing"

如果 Cache 或 Registry 缺失，重新执行安装步骤。

自定义配置

HUD 启动后，随时运行以下命令调整显示：

/claude-hud:configure

或直接编辑配置文件：

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

常用配置项：

{
  "lineLayout": "compact",
  "language": "zh",
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showDuration": true,
    "usageBarEnabled": true
  },
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true
  }
}

参考

posted on 2026-05-13 13:57 茶倌阅读(72) 评论(0) 收藏举报