By Jermine

背景

Claude Code 是 Anthropic 的终端 AI 编程助手，但它默认不显示任何会话状态信息——当前在处理什么任务、调用了哪些工具、用了什么模型、会话跑了多久，这些信息你只能在滚动历史里翻。

Claude HUD 是一个 Claude Code 插件，它在终端输入框下方常驻显示一个状态行（statusLine），实时展示当前会话的关键信息。

效果

安装后，每次启动 Claude Code 都会在底部看到一个信息条，可以显示：

  • 工具活动：当前运行/已完成的工具调用（如 Edit: file.ts | Read x3）
  • 子代理和任务进度：子代理状态和 todo 列表进度
  • 会话信息：会话持续时长、加载的 CLAUDE.md、rules、MCP 数量
  • 会话名称：自定义的会话标题或自动生成的 slug

这些都是可选的，默认只显示基础的两行状态。

环境要求

  • Claude Code 已安装
  • Node.js 或 Bun 运行时（用于执行 HUD 脚本）
  • Linux / macOS（Windows 也支持，但配置方式略有不同）

我的环境：

项目 值
平台 Linux (6.17.0)
Shell zsh
运行时 Bun
Node.js v22.22.2

安装步骤

1. 安装插件

在 Claude Code 终端中运行：

1/plugin marketplace add jarrodwatts/claude-hud
2/plugin install claude-hud

安装成功后会提示：

Successfully added marketplace: claude-hud
✓ Installed claude-hud. Run /reload-plugins to apply.

2. 重载插件

1/reload-plugins

输出示例：

Reloaded: 4 plugins · 81 skills · 97 agents · 41 hooks · 7 plugin MCP servers

3. 运行安装向导

1/claude-hud:setup

这个命令会自动完成以下步骤：

3.1 检测运行时

脚本优先检测 bun（性能更好），没有则回退到 node：

1command -v bun 2>/dev/null || command -v node 2>/dev/null

在我的机器上输出：

/home/jm/.bun/bin/bun

3.2 定位插件路径

自动找到最新版本的插件缓存目录（按版本号排序）：

1ls -d "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/*/claude-hud/*/ 2>/dev/null \
2  | awk -F/ '{ print $(NF-1) "\t" $(0) }' \
3  | grep -E '^[0-9]+\.[0-9]+\.[0-9]+[[:space:]]' \
4  | sort -t. -k1,1n -k2,2n -k3,3n -k4,4n | tail -1 | cut -f2-

输出：

/home/jm/.claude/plugins/cache/claude-hud/claude-hud/0.1.0/

3.3 生成 statusLine 命令

根据运行时类型生成不同的命令：

  • Bun 运行时：使用 src/index.ts 并添加 --env-file /dev/null 防止自动加载项目的 .env 文件
  • Node 运行时：使用 dist/index.js

Bun 生成的命令格式：

1bash -c 'cols=$(stty size </dev/tty 2>/dev/null | awk '"'"'{print $1}'"'"'); \
2  export COLUMNS=$(( ${cols:-120} > 4 ? ${cols:-120} - 4 : 1 )); \
3  plugin_dir=$(ls -d "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/*/claude-hud/*/ 2>/dev/null \
4    | awk -F/ '"'"'{ print $(NF-1) "\t" $(0) }'"'"' \
5    | grep -E '"'"'^[0-9]+\.[0-9]+\.[0-9]+[[:space:]]'"'"' \
6    | sort -t. -k1,1n -k2,2n -k3,3n -k4,4n | tail -1 | cut -f2-); \
7  exec "/home/jm/.bun/bin/bun" --env-file /dev/null "${plugin_dir}src/index.ts"'

命令做了三件事：

  1. 通过 stty size 获取终端宽度，写入 COLUMNS 环境变量
  2. 动态查找最新版本插件路径（更新插件后无需重新配置）
  3. 用 exec 启动 HUD 进程，持续输出状态行内容

3.4 写入配置

将 statusLine 写入 ~/.claude/settings.json：

1{
2  "statusLine": {
3    "type": "command",
4    "command": "bash -c 'cols=$(stty size </dev/tty ...'"
5  }
6}

写入时需要注意 JSON 格式安全——awk 里的反斜杠 \\$(NF-1) 在 JSON 中必须转义，否则 HUD 启动时会报 Module not found。

3.5 可选功能配置

运行 /claude-hud:setup 时会询问是否启用额外功能。选择后写入 ~/.claude/plugins/claude-hud/config.json：

 1{
 2  "display": {
 3    "showTools": true,
 4    "showAgents": true,
 5    "showTodos": true,
 6    "showDuration": true,
 7    "showConfigCounts": true,
 8    "showSessionName": true
 9  }
10}

4. 重启验证

配置写入后必须重启 Claude Code 才能生效：

1# 退出当前会话，重新运行
2claude

重启后输入框下方应该会出现 HUD 状态行。

常见问题排查

HUD 不显示

  1. 确认已重启：statusLine 配置需要重启才生效
  2. 检查 settings.json：确认 statusLine.command 字段存在且格式正确
  3. 手动测试命令： 
    1# 复制 settings.json 里 statusLine.command 的值手动运行
2cols=$(stty size </dev/tty 2>/dev/null | awk '{print $1}'); \
3  export COLUMNS=$(( ${cols:-120} > 4 ? ${cols:-120} - 4 : 1 )); \
4  plugin_dir=$(ls -d "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/*/claude-hud/*/ 2>/dev/null | sort -V | tail -1); \
5  /home/jm/.bun/bin/bun --env-file /dev/null "${plugin_dir}src/index.ts"

运行时路径变了

如果用 mise/nvm/asdf 管理运行时版本，绝对路径可能过时：

1# 重新检测
2command -v bun    # 或 command -v node
3realpath $(command -v bun)  # 确认真实路径

然后重新运行 /claude-hud:setup。

插件找不到

1# 确认插件已安装
2ls "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/*/claude-hud/

如果为空，重新 /plugin install claude-hud。

grep 匹配问题

命令里的 grep -E 模式必须使用 [[:space:]] 而非 \t。GNU grep 不识别 \t 为制表符，会报 warning: stray \ before t，导致 plugin_dir 解析为空。这是官方安装指南特别强调的细节。

插件更新后

不需要重新运行 setup。命令中的动态版本查找会自动指向最新版本。如果 HUD 突然不工作了，再重新 /claude-hud:setup 验证。

手动安装（不用向导）

如果你不想运行 /claude-hud:setup 向导，也可以手动完成：

 1# 1. 检测运行时
 2RUNTIME=$(command -v bun || command -v node)
 3
 4# 2. 找到插件路径
 5PLUGIN_DIR=$(ls -d "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/*/claude-hud/*/ 2>/dev/null \
 6  | sort -V | tail -1)
 7
 8# 3. 确认源码文件
 9# Bun 用 src/index.ts，Node 用 dist/index.js
10if [ -f "$PLUGIN_DIR/src/index.ts" ]; then
11  SOURCE="$PLUGIN_DIR/src/index.ts"
12else
13  SOURCE="$PLUGIN_DIR/dist/index.js"
14fi
15
16# 4. 生成命令
17CMD="bash -c 'cols=\$(stty size </dev/tty 2>/dev/null | awk '"'"'{print \$1}'"'"'); export COLUMNS=\$(( \${cols:-120} > 4 ? \${cols:-120} - 4 : 1 )); plugin_dir=\$(ls -d \"\${CLAUDE_CONFIG_DIR:-\$HOME/.claude}\"/plugins/cache/*/claude-hud/*/ 2>/dev/null | awk -F/ '"'"'{ print \$(NF-1) \"\\t\" \$(0) }'"'"' | grep -E '"'"'^[0-9]+\\.[0-9]+\\.[0-9]+[[:space:]]'"'"' | sort -t. -k1,1n -k2,2n -k3,3n -k4,4n | tail -1 | cut -f2-); exec \"$RUNTIME\" --env-file /dev/null \"\${plugin_dir}src/index.ts\"'"
18
19# 5. 用 node 写进 settings.json（避免手动拼接 JSON 的转义坑）
20node -e "
21const fs = require('fs');
22const p = '$HOME/.claude/settings.json';
23const s = JSON.parse(fs.readFileSync(p, 'utf8'));
24s.statusLine = { type: 'command', command: \`$CMD\` };
25fs.writeFileSync(p, JSON.stringify(s, null, 2) + '\\n');
26"

总结

Claude HUD 是一个实用的小插件，解决了 Claude Code 缺乏常驻状态显示的问题。安装流程的核心就三步：装插件、写 statusLine、重启。向导 /claude-hud:setup 帮你自动搞定路径和转义，比自己手拼 JSON 命令靠谱得多。

相关链接：

相关文章