第一部分概述

在使用 Claude Code 进行开发时，我们常常面临一个信息不对称的问题：AI 助手在后台究竟在做什么？上下文窗口还剩多少？有哪些子代理正在运行？直到最近，这些问题都难以直观地回答。

Claude HUD 是由 Jarrod Watts 开发的一款 Claude Code 插件，它为终端会话带来了类似"平视显示器"（Head-Up Display）的体验。这款插件通过在输入框下方常驻显示关键信息，让开发者能够实时掌握会话状态，从而更高效地管理复杂的多步骤任务。

1.1 核心定位

Claude HUD 并非独立的 GUI 应用，而是深度集成于 Claude Code 的 statusline API。它不依赖 tmux 或单独窗口，在任何终端环境中都能工作。通过解析 Claude Code 的 stdin JSON 数据流和 transcript 日志，HUD 能够以约 300ms 的刷新频率更新状态，提供近乎实时的反馈。

12 解决的关键痛点

传统痛点	Claude HUD 的解决方案
上下文窗口"突然爆满"	可视化进度条 + 百分比显示，支持 1M 上下文会话
不清楚 AI 正在读取/编辑哪些文件	实时工具活动追踪（Read/Edit/Grep 等）
子代理（Subagents）黑盒运行	显示代理名称、任务描述和运行时长
待办事项列表状态不明	实时进度更新（如 "2/5"）
订阅额度使用情况模糊	原生 API 数据展示（小时/周度限制）

1.3 技术架构


Claude Code → stdin JSON → claude-hud → stdout → 终端显示
           ↘ transcript JSONL (工具/代理/待办数据)

该插件使用 Claude Code 提供的原生 token 数据（非估算值），并自动适配 Claude Code 报告的上下文窗口大小。这种设计确保了数据的准确性，同时避免了插件本身对 API 凭证的依赖或后台轮询未公开端点的需求。

1.4 安装门槛

Claude Code: v1.0.80+
运行时: Node.js 18+ 或 Bun
平台: 跨平台支持（Windows/macOS/Linux），但 Linux 用户需注意 tmpfs 文件系统限制

1.5 使用场景

Claude HUD 特别适合以下场景：

长会话开发：当与 Claude 进行数小时的结对编程时，监控上下文消耗至关重要
多代理协作：使用 Claude 的子代理（Subagents）功能并行处理多个任务时
MCP 工具链调试：需要观察 MCP 服务器调用频率和响应时
团队协作：通过 Git 状态显示（分支、未提交更改、超前/落后提交数）快速确认工作环境

第二部分功能特性

2.1 双层信息架构

Claude HUD 采用"2+N"行显示策略：

默认基础层（2行）：


[Opus] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)

第1行：当前模型（如 Opus、Bedrock）、项目路径（可配置 1-3 级目录）、Git 分支
第2行：上下文健康度（绿→黄→红渐变进度条）和订阅额度使用率

可选扩展层（通过配置启用）：


◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2        ← 工具活动
◐ explore [haiku]: Finding auth code (2m 15s)    ← 代理状态
▸ Fix authentication bug (2/5)                   ← 待办进度

2.2 深度配置能力

插件提供了引导式配置流程（/claude-hud:configure）和高级 JSON 配置两种方式：

预设模式：

Full: 显示所有信息（工具、代理、待办、Git、额度、时长）
Essential: 活动行 + Git 状态，平衡信息密度
Minimal: 仅模型名和上下文条，最精简

高阶自定义：

路径层级: pathLevels（1-3）控制显示 my-project 还是 dev/apps/my-project
颜色系统: 支持 ANSI 颜色名、256 色或十六进制值（#rrggbb）
国际化: 原生支持中文标签（通过 language: zh 启用）
Git 细节: 脏标记（*）、超前/落后计数（↑2 ↓1）、文件统计（!3 +1 ?2）

2.3 智能阈值预警

上下文警告: 85%+ 显示详细 token 分解（输入/输出/缓存）
额度预警: 7 天使用率超过阈值（默认 80%）时自动显示
Git 推送警告: 可配置未推送提交数阈值（如 ≥5 个变红提示）

第三部分安装与配置

3.1 快速安装

bash
# Step 1: 添加插件市场
/plugin marketplace add jarrodwatts/claude-hud

# Step 2: 安装插件
/plugin install claude-hud

# Step 3: 运行配置向导
/claude-hud:setup

注意：

Linux 用户：若 /tmp 是独立文件系统（tmpfs），需设置 TMPDIR 环境变量避免 EXDEV 错误
Windows 用户：若提示缺少 JavaScript 运行时，需先安装 Node.js LTS（winget install OpenJS.NodeJS.LTS）

安装完成后，必须重启 Claude Code 以加载新的 statusLine 配置。

3.2 配置示例

以下是一个面向中文用户的完整配置：

json
{
  "language": "zh",
  "lineLayout": "expanded",
  "pathLevels": 2,
  "elementOrder": ["project", "tools", "context", "usage", "agents", "todos"],
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": true
  },
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showConfigCounts": true,
    "showDuration": true,
    "contextValue": "both"
  },
  "colors": {
    "context": "cyan",
    "usage": "cyan",
    "warning": "yellow",
    "critical": "red"
  }
}

此配置将显示：

中文标签（上下文、使用率等）
2 级目录路径（如 apps/my-project）
Git 分支、脏标记、超前/落后状态
工具活动、代理状态、待办进度
上下文同时显示百分比和具体 token 数

第四部分使用体验

4.1 上下文管理的范式转变

在没有 HUD 之前，开发者往往通过"感觉"来判断上下文是否接近极限——直到 Claude 开始遗忘早期对话内容。Claude HUD 将抽象的 token 计数转化为直观的进度条：


Context ██████░░░░ 60%

当超过 85% 时，会自动展开显示详细分解：


Context █████████░ 90% (90k/100k) | 缓存: 45k | 输入: 30k | 输出: 15k

这种设计让长会话编程变得可预测，开发者可以主动使用 /clear 或总结历史来管理上下文。

4.2 多代理协作的可视化

Claude Code 的子代理功能是强大的并行计算能力，但也带来了"黑盒"问题。HUD 的代理状态行解决了这一点：


◐ explore [haiku]: Finding auth code (2m 15s)
◑ optimize [opus]: Refactoring database queries (45s)
✓ test [haiku]: Running unit tests (completed in 30s)

每个代理显示：

状态符号: ◐（进行中）、◑（暂停/等待）、✓（完成）、✗（错误）
代理名称: 如 explore、optimize
所用模型: 方括号内显示，如 [haiku]、[opus]
当前任务: 简短描述
运行时长: 实时更新

这让开发者能够监控并行任务进度，及时发现卡住的代理。

4.3 工具链的透明化

对于使用 MCP（Model Context Protocol）服务器的场景，HUD 的工具行提供了关键洞察：


✓ Read ×3 | ✓ Grep ×2 | ◐ Edit: src/auth.ts | ✓ mcp__context7 ×1

这显示了：

工具类型: Read、Edit、Grep、Glob、TaskOutput 等
调用次数: 如 ×3
当前操作: 如 Edit: src/auth.ts
MCP 调用: 特定 MCP 服务器的调用（如 mcp__context7）

对于调试复杂工具链或优化性能（减少不必要的文件读取）非常有价值。

4.4 订阅额度管理

对于 Claude Pro/Team 订阅用户，HUD 集成显示了官方速率限制：


Usage ██░░░░░░░░ 25% (1h 30m / 5h) | ██████████ 85% (2d / 7d)

这包括：

当前窗口: 通常是 5 小时内的使用量
7 天窗口: 当周累计使用量（超过阈值时显示）

重要限制：

仅支持官方订阅账号（非 API Key 用户）
AWS Bedrock 等路由提供商显示 Bedrock 标签但隐藏额度（额度在 AWS 端管理）
部分 Claude Code 构建版本可能不暴露 rate_limits 数据

第五部分总结

Claude HUD 代表了开发者工具的一个趋势：将 AI 助机的内部状态外化为可观测的界面。它不是要取代 Claude Code 的交互，而是通过信息层的增强，让开发者从"盲目信任"转向"知情掌控"。

5.1 优势

零摩擦集成: 无需额外窗口，利用 Claude Code 原生 API
数据准确性: 使用官方 token 计数和额度数据，非估算
高度可定制: 从 Minimal 到 Full，适应不同信息密度偏好
国际化支持: 原生中文界面，降低非英语用户认知负担
开源透明: MIT 协议，社区可参与改进

5.2 局限与注意事项

平台限制: Linux 需处理 tmpfs 问题，Windows 需 Node.js 环境
数据依赖: 部分功能（如额度显示）依赖 Claude Code 的官方数据暴露
性能考虑: 虽然 300ms 刷新率很高效，但在极低延迟场景下需关注 CPU 占用
配置复杂度: 高级定制需要直接编辑 JSON，对非技术用户有一定门槛

5.3 适用人群

重度 Claude Code 用户: 每天使用数小时的开发者
团队技术负责人: 需要监控多代理任务和工具使用情况的架构师
AI 辅助编程学习者: 通过观察工具调用学习 Claude 如何思考
资源敏感型用户: 严格管理上下文和 API 额度的场景

5.4 展望未来

随着 Claude Code 生态的成熟，类似 HUD 的状态可视化工具可能会成为标准配置。Claude HUD 的开源实现为社区提供了一个优秀的参考范式——不侵入核心流程，通过标准 API 扩展能力。

对于希望提升 Claude Code 使用体验的开发者，Claude HUD 是一个强烈推荐的插件。它用极低的配置成本，换来了对 AI 协作过程的深度可见性，这在复杂工程任务中尤为宝贵。

本文基于 Claude HUD 开源仓库内容撰写，功能细节可能随版本更新而变化，请以官方文档为准。

目录

第一部分 概述