Claude HUD 安装与配置：终端状态行实时监控上下文与工具活动

2026-06-11claude-code · claude-hud · 监控 · 状态行 · 效率 · 插件

Claude HUD 是一个 Claude Code 状态行插件，在终端输入行下方常驻显示上下文使用率、活跃工具、子 Agent 状态和 Todo 进度。由社区开发者 jarrodwatts 维护，通过 Claude Code 原生 statusline API 实现，不需要独立窗口或 tmux。

写作环境：Windows 11 + PowerShell 7 + Claude Code v2.x + Claude HUD（2026-06 验证）。

一、安装

1.1 前提条件

Claude HUD 是一个 Node.js 进程，运行它的机器上需要安装 Node.js 18+。

powershell

# Windows — 如未安装 Node.js，先用 winget 安装

winget install OpenJS.NodeJS.LTS

# macOS

brew install node

# Linux

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

sudo apt install -y nodejs

1.2 三步安装

在 Claude Code 会话中依次执行以下命令：

bash

# 步骤 1：添加插件市场

/plugin marketplace add jarrodwatts/claude-hud

# 步骤 2：安装插件

/plugin install claude-hud

# 步骤 3：重新加载插件使安装生效

/reload-plugins

# 步骤 4：运行 setup 生成状态行配置

/claude-hud:setup

Linux 注意

Linux 上 /tmp 可能是独立的 tmpfs 文件系统，插件安装时会报 EXDEV: cross-device link not permitted 错误。解决：在运行 /plugin install 之前设置 TMPDIR=~/.cache/tmp。

/claude-hud:setup 会自动检测平台、shell 和运行时，生成 statusline 配置写入 ~/.claude/settings.json，然后提示重启 Claude Code。重启后终端输入行下方出现两行状态信息，安装完成。

二、配置

安装后可通过交互式命令或直接编辑配置文件来调整显示内容。

2.1 交互式配置

bash

/claude-hud:configure

这个命令会引导你逐步选择：

布局：Expanded（多行）或 Compact（单行）
预设：Full（全部显示）、Essential（核心信息）、Minimal（仅上下文条）
语言：英文（en）或中文（zh-Hans），影响标签文字
各元素开关：逐一开启或关闭工具活动、子 Agent、Todo、使用率等

2.2 配置文件

配置文件路径：~/.claude/plugins/claude-hud/config.json。交互式配置的结果写入这个文件，也可以直接编辑。

主要配置项速查

配置项	取值	说明
`lineLayout`	`"expanded"` / `"compact"`	多行或单行布局
`language`	`"en"` / `"zh-Hans"`	界面标签语言
`elementOrder`	字符串数组	元素排列顺序
`pathLevels`	1-3	路径显示深度
`display.tools`	bool	工具活动追踪
`display.agents`	bool	子 Agent 状态
`display.todos`	bool	Todo 进度
`display.context`	bool	上下文使用率条
`display.usage`	bool	使用率限制与时长

三、实际效果

Expanded 布局下，状态行显示两行信息。示意如下：

text

[Opus] │ ai-tools-guide git:(master*)

上下文 ██████░░░░ 45% │ 使用率 ██░░░░░░░░ 25%（1h 30m / 5h）

# 当工具活跃时，第一行追加工具状态：

[Opus] │ ◐ Edit: auth.ts ✓ Read x3 │ ai-tools-guide git:(master*)

上下文 ██████░░░░ 45% │ 使用率 ██░░░░░░░░ 25%

# 当子 Agent 运行时：

[Opus] │ ◐ explore [haiku]: 查找认证代码 │ ai-tools-guide git:(master*)

上下文 ██████░░░░ 45% │ 使用率 ██░░░░░░░░ 25%

# Todo 进行中时：

[Opus] │ ▸ 修复认证漏洞（2/5）│ ai-tools-guide git:(master*)

上下文 ██████░░░░ 45% │ 使用率 ██░░░░░░░░ 25%

Compact 布局将所有信息压缩到一行，适合窄终端或偏好简洁的场景。

使用率仅对 Claude 订阅用户可用

「使用率」显示的数据来自 Claude Code 的 rate_limits 输入——只有 Pro/Max 订阅用户才会收到此数据。API Key 用户（包括 DeepSeek API、第三方 Key）没有 rate_limits 数据源，开了 showUsage 也不会显示，不是配置问题。

核心价值

上下文可见：不再需要频繁敲 /context 查看用量，状态行实时更新
工具追踪：Claude 正在读哪个文件、编辑哪个文件，一目了然
子 Agent 监控：后台派出的子 Agent 状态不会丢失——状态行显示它在做什么、用哪个模型
用量感知：Token 速度和时长提示，帮助判断是否快触发限速

HUD 与 /context 命令的区别

/context 是一次性快照，需要手动执行。HUD 是实时更新（约每 300ms 刷新一次），始终显示在输入行下方。 HUD 不替代 /context——后者展示更详细的 Token 分布（文件、工具调用、对话历史各自占比）， HUD 提供的是持续可见的简要状态。

四、与其他工具的关系

HUD 是可观测性工具——让你看见 Claude Code 在做什么。如果要让 Claude Code 按工程规范做事（设计→计划→TDD→审查），需要工作流层面的工具，如Superpowers 工作流框架。两者互不冲突，可以同时安装——HUD 让你看见流程，Superpowers 让流程有纪律。

Starship v1.25.0 也提供了 starship statusline claude-code 子命令，能在提示符中嵌入模型名和上下文用量。与 HUD 相比更轻量，但不显示工具活动、子 Agent 状态和 Todo 进度。详见终端美化指南。

五、验证

安装完成后逐条确认：

Claude Code 输入行下方出现状态栏，显示模型名和上下文使用率
执行 /context，状态行的百分比与命令输出一致
让 Claude 读取一个文件，状态行出现文件读写活动
触发一个子 Agent 任务（如让 Claude "探索这个目录结构"），状态行显示 Agent 名称和状态
运行 /claude-hud:configure 切换布局后状态行立即变化

时效性说明

⚠️ 以上信息可能已过时，请以各平台官方网站的最新公告和定价页面为准。本文基于 Claude Code v2.x + Claude HUD（jarrodwatts/claude-hud）验证，写作日期 2026-06-11。Claude HUD 是社区插件，功能可能随版本变化，以 GitHub 仓库最新文档为准。