Claude HUD：让 AI 编程助手告别黑盒

Claude Code 有时像个黑箱——你给它一个任务，它开始执行，但过程中你完全不知道它在做什么。是在读文件？编辑代码？还是已经启动了 subagent？

苏米注：这是所有使用 CLI 编程工具的人都会遇到的问题。缺乏可见性，让人难以信任和调试 AI 的行为。

最近走红的 Claude HUD 插件，正好解决了这个痛点。它能在不打开新窗口、也不依赖 tmux 的情况下，实时显示 Claude Code 会话的内部状态。

Claude HUD 会显示在输入框下方，大约每 300ms 更新一次，提供四类关键信息：

• Context Window 使用情况：彩色进度条，让你提前预知上下文占用
• Tool Activity：实时显示 Claude 正在读取、编辑或搜索哪些文件
• Agent Tracking：跟踪 subagents 的运行状态
• Todo Progress：显示当前任务进度

Claude HUD 的四行信息显示

Claude HUD 最多渲染四行信息，每行代表会话的不同维度。

第一行：Session Info（始终可见）

📁 my-project | [Opus 4.6] ████░░░░░░ 19% | 2 CLAUDE.md | 8 rules | 6 MCPs | 6 hooks | ⏱️ 1m

这一行包含以下信息：

• Model：当前运行的模型（Opus、Sonnet、Haiku）
• Context Bar：10 格可视化进度条，随上下文占用从绿→黄→红变化
• Config Counts：已加载的 CLAUDE.md、rules、MCPs、hooks 数量
• Session Timer：当前会话运行时长

第二行：Tool Activity（实时工具活动）

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

这一行展示 Claude 在文件层面的实时操作：

• 正在运行的工具显示旋转指示器和目标文件
• 已完成的工具按类型聚合显示次数
• 避免多条条目挤占显示空间

苏米注：这个聚合设计很聪明。当 Claude 读取 5 个文件时，你看到的是"✓ Read ×5"而不是 5 条独立记录，保持界面清爽。

第三行：Agent Status（子代理追踪）

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

当 Claude 启动 subagents 时，这一行会显示：

• Agent 类型（如 explore、specialized task）
• 当前任务描述
• 已运行时长

使用 agent teams 或并行任务时，这里会显示多条记录——每个活跃 agent 一行。

第四行：Todo Progress（任务进度）

▸ Fix authentication bug (2/5)

显示当前激活任务的完成进度。全部完成后会显示：

✓ All todos complete (5/5)

三步安装 Claude HUD

在已激活的 Claude Code 会话中执行以下三条命令：

步骤一：添加 Marketplace

/plugin marketplace add jarrodwatts/claude-hud

将 GitHub 仓库注册为插件源。

步骤二：安装插件

/plugin install claude-hud

安装成功后会提示：

Installed claude-hud. Run /reload-plugins to activate.

步骤三：配置 Statusline

/claude-hud:setup

自动将 statusline 配置写入 ~/.claude/settings.json，无需手动编辑。

Setup 过程中可以选择启用可选功能：

1. Tools activity - 显示运行/完成的工具
2. Agents & Todos - 显示 subagent 状态和任务进度
3. Session info - 显示会话时长和配置数量
4. Session name - 显示会话名称或自定义标题

踩坑记录：运行完 setup 后需要重启 Claude Code，HUD 才会立即显示。

平台特定注意事项

Linux 用户

/tmp 通常是独立的 tmpfs 文件系统，可能导致跨设备链接错误。解决方案：

mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude

在该会话中执行安装命令。

Windows 用户

如果 setup 提示未找到 JavaScript 运行时，先安装 Node.js LTS：

winget install OpenJS.NodeJS.LTS

重启 shell 后再次运行 /claude-hud:setup。

故障排查

如果 HUD 未显示，尝试以下方法：

1. 完全重启 Claude Code：不是仅关闭提示框，而是彻底退出再重新启动
2. 检查插件列表：运行 /plugin list 确认 claude-hud 在列表中
3. 重新安装：如果不在列表中，重复安装步骤

高级配置

HUD 运行后，可通过编辑以下文件进行自定义：

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

可调整项包括颜色、路径显示层级、阈值覆盖等。运行 /claude-hud:configure 会保留手动设置，插件更新时不会丢失配置。

苏米注：插件更新是自动的，这点很省心。配置持久化也是关键设计，避免每次更新都要重新调校。

使用体验总结

Claude HUD 属于"装上就回不去"的增强工具：

• Context Bar：无需中途运行 /context 命令，一眼掌握上下文状态
• Tool Activity：处理多文件任务时尤其有用，确认 Claude 仍在推进而非卡住
• Agent Tracking：并行运行多个 subagent 时，帮助理解 AI 的决策过程

对于重度使用 Claude Code 的开发者来说，这个插件显著提升了透明度和可控性。