克劳德 HUD

一个显示当前状态的 Claude Code 插件——包括上下文使用情况、活跃工具、运行中的代理以及待办事项进度。始终位于输入框下方可见。

安装

在 Claude Code 实例中，运行以下命令：

步骤 1：添加插件市场

/plugin marketplace add jarrodwatts/claude-hud

步骤 2：安装插件

EXDEV: 跨设备链接不允许

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

/plugin install claude-hud

之后，重新加载插件：

/reload-plugins

步骤 3：配置状态栏

/claude-hud:setup

winget install OpenJS.NodeJS.LTS

完成！重启 Claude Code 以加载新的 statusLine 配置，HUD 就会显示出来。

在 Windows 上，设置完成后需要完全重启 Claude Code，以便新 statusLine 配置生效。

什么是 Claude HUD？

Claude HUD 可以让你更好地了解当前 Claude Code 会话中的动态。

显示内容

默认（2 行）

[Opus] │ my-project git:(main*)
上下文 █████░░░░░ 45% │ 使用量 ██░░░░░░░░ 25% (1h 30m / 5h)

• 第 1 行 — 模型名称、识别出的服务提供商标签（例如 Bedrock）、项目路径、Git 分支
• 第 2 行 — 上下文条形图（绿色 → 黄色 → 红色）以及使用率限制

可选行（通过 /claude-hud:configure 启用）

◐ 编辑：auth.ts | ✓ 读取 ×3 | ✓ Grep ×2        ← 工具活动
◐ explore [haiku]: 寻找认证代码（2 分 15 秒）    ← 代理状态
▸ 修复认证漏洞（2/5）                   ← 待办进度

工作原理

Claude HUD 使用 Claude Code 原生的 statusline API — 不需要额外窗口，也不需要 tmux，在任何终端中均可正常工作。

Claude Code → stdin JSON → claude-hud → stdout → 在你的终端中显示
           ↘ 转录日志 JSONL（工具、代理、待办事项）

主要特点：

• 直接使用 Claude Code 提供的原生 token 数据（而非估算值）
• 能够根据 Claude Code 报告的上下文窗口大小进行缩放，包括最新的 100 万 token 上下文会话
• 解析转录日志以获取工具和代理活动信息
• 每约 300 毫秒更新一次

配置

随时自定义你的 HUD：

/claude-hud:configure

引导式流程可以处理布局、语言以及常见显示选项的切换。高级覆盖设置，如自定义颜色和阈值，也会被保留，但你需要直接编辑配置文件来调整：

• 首次设置：选择预设（完整/基础/简约），挑选标签语言，然后微调各个元素
• 随时自定义：开启或关闭特定项目，调整 Git 显示样式，切换布局，或更改标签语言
• 保存前预览：在提交更改之前，精确查看 HUD 的最终外观

预设

选择预设后，你可以单独开启或关闭某些元素。

手动配置

直接编辑 ~/.claude/plugins/claude-hud/config.json 文件，以进行高级设置，例如 colors.*、pathLevels 和阈值覆盖。运行 /claude-hud:configure 会保留这些手动设置，同时仍允许你更改语言、布局以及常见的引导式切换选项。

中文 HUD 标签需明确选择启用。默认语言为英语，除非你在 /claude-hud:configure 中选择“中文”，或在配置文件中设置 language 为“中文”。

选项

支持的颜色名称：dim、red、green、yellow、magenta、cyan、brightBlue、brightMagenta。您也可以使用 256 色编号（0-255）或十六进制（#rrggbb）。

display.showMemoryUsage 完全由用户选择开启，且仅在 expanded 布局中渲染。它报告的是本地机器上的近似系统 RAM 使用情况，而不是 Claude Code 内部或特定进程中的精确内存压力。该数字可能会夸大实际压力，因为可回收的 OS 缓存和缓冲区仍可能被计入已使用内存。

display.showCost 完全由用户选择开启。ClaudeHUD 更倾向于使用 Claude Code 在标准输入上提供的原生 cost.total_cost_usd 字段（如果可用）。如果该字段不存在或对于直接 Anthropic 会话无效，ClaudeHUD 会回退到现有的基于本地对话记录的估算值，以便成本行在旧版本负载中也能正常工作。原生字段在会话首次 API 响应之前是不存在的，因此成本显示可能会一直隐藏到那时。ClaudeHUD 还会针对已知的代理提供商（如 Bedrock）隐藏成本，因为云服务提供商计费的会话可能会显示 $0.00 或省略该字段，即使会话并非真正免费。

使用限制

当 Claude Code 在标准输入上提供订阅者 rate_limits 数据时，使用情况显示会 默认启用。它会在第 2 行与上下文条一起显示您的速率限制使用情况。

ClaudeHUD 故意只信任官方的状态行标准输入负载来获取实时使用情况，不会读取本地 OAuth 凭证或在后台轮询未公开的使用端点。

仅限免费或每周使用的账户会单独显示每周窗口，而不会显示 5h: -- 的占位符。

当使用量超过 display.sevenDayThreshold（默认 80%）时，会显示 7 天百分比：

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

要禁用，请将 display.showUsage 设置为 false。

要求：

• Claude Code 必须在当前会话的标准输入中包含订阅者 rate_limits 数据
• 不适用于仅使用 API 密钥的用户

故障排除： 如果使用情况未显示：

• 确保您已使用 Claude 订阅者账户登录（而非 API 密钥）
• 检查配置中是否将 display.showUsage 设置为 false
• API 用户不会看到使用情况显示（他们采用按 token 支付，而非速率限制）
• AWS Bedrock 模型会显示 Bedrock 并隐藏使用限制（使用情况由 AWS 管理）
• Claude Code 可能在会话首次模型响应之前仍将 rate_limits 留空
• 某些 Claude Code 构建版本和订阅层级可能即使在首次响应后仍会省略 rate_limits
• 当 rate_limits 不存在时，ClaudeHUD 会隐藏使用情况，而不会回退到凭据抓取或未公开的 API 调用

配置示例

{
  "language": "zh",
  "lineLayout": "expanded",
  "pathLevels": 2,
  "elementOrder": ["project", "tools", "context", "usage", "memory", "environment", "agents", "todos"],
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": true
  },
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showConfigCounts": true,
    "showDuration": true,
    "showMemoryUsage": true
  },
  "colors": {
    "context": "cyan",
    "usage": "cyan",
    "warning": "yellow",
    "usageWarning": "magenta",
    "critical": "red",
    "model": "cyan",
    "project": "yellow",
    "git": "magenta",
    "gitBranch": "cyan",
    "label": "dim",
    "custom": "#FF6600"
  }
}

显示示例

1 层（默认）： [Opus] │ my-project git:(main)

2 层： [Opus] │ apps/my-project git:(main)

3 层： [Opus] │ dev/apps/my-project git:(main)

带脏状态指示符： [Opus] │ my-project git:(main*)

带领先/落后信息： [Opus] │ my-project git:(main ↑2 ↓1)

带文件统计信息： [Opus] │ my-project git:(main* !3 +1 ?2)

• ! = 已修改文件，+ = 新增/暂存文件，✘ = 已删除文件，? = 未跟踪文件
• 为保持显示整洁，计数为 0 的项将被省略

故障排除

配置未生效？

• 检查 JSON 语法错误：无效的 JSON 会静默回退到默认设置
• 确保使用有效值：pathLevels 必须为 1、2 或 3；lineLayout 必须为 expanded 或 compact
• 删除配置并运行 /claude-hud:configure 以重新生成配置

Git 状态缺失？

• 确认当前处于 Git 仓库中
• 检查配置中的 gitStatus.enabled 是否未设置为 false

工具/代理/待办事项行缺失？

• 这些内容默认隐藏——可通过在配置中启用 showTools、showAgents 和 showTodos 来显示
• 此外，只有当有相关活动时才会显示

设置后 HUD 仍未出现？

• 重启 Claude Code，以便其加载新的 statusLine 配置
• 在 macOS 上，请完全退出 Claude Code，并在终端中重新运行 claude

需求

• Claude Code v1.0.80+
• Node.js 18+ 或 Bun

开发

git clone https://github.com/jarrodwatts/claude-hud
cd claude-hud
npm ci && npm run build
npm test

有关指南，请参阅 CONTRIBUTING.md。

许可证

MIT — 详情请参阅 LICENSE

星标历史

Claude HUD 快速上手指南

Claude HUD 是一款专为 Claude Code 设计的插件，能够在终端输入框下方实时显示上下文使用率、活跃工具、运行中的子代理（Agents）以及待办事项进度，让你对当前会话状态一目了然。

环境准备

在开始之前，请确保满足以下条件：

• 核心依赖：已安装并配置好 Claude Code。
• 操作系统：支持 Linux、macOS 和 Windows。
• JavaScript 运行时（Windows 用户必读）：
  • Windows 用户需要安装 Node.js LTS 以支持插件设置功能。
  • 如果未安装，请在 PowerShell 中运行：

    winget install OpenJS.NodeJS.LTS
    

  • 安装完成后重启终端。
• Linux 用户注意：
  • 由于 /tmp 通常是独立文件系统，可能导致安装失败。建议在安装前设置临时目录：

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

  • 请在执行上述命令后的新会话中进行安装操作。

安装步骤

请在 Claude Code 的交互界面中依次执行以下命令：

第一步：添加插件市场源

/plugin marketplace add jarrodwatts/claude-hud

第二步：安装插件

/plugin install claude-hud

第三步：重载插件列表

/reload-plugins

第四步：初始化配置

/claude-hud:setup

• 执行此命令后，跟随引导选择预设模式（Full/Essential/Minimal）及语言偏好。
• 重要：配置完成后，请完全重启 Claude Code（退出并重新进入），以使新的状态栏配置生效。

基本使用

安装并重启后，Claude HUD 将自动在终端底部显示状态信息，无需额外命令。

1. 默认显示效果

启动后，你将看到类似以下的两行状态信息：

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

• 第一行：显示当前模型、项目路径及 Git 分支状态。
• 第二行：可视化展示上下文窗口使用率（颜色随负载变红）及订阅用量限制。

2. 开启更多功能（可选）

默认仅显示核心信息。若需查看工具活动、Agent 状态或待办进度，可运行配置命令开启：

/claude-hud:configure

在引导流程中，你可以：

• 切换语言为 中文 (zh)。
• 启用 Tools activity（文件读写监控）、Agent status（子代理任务）或 Todo progress（任务进度）。
• 调整布局为单行紧凑模式或多行详细模式。

3. 高级自定义

如需修改颜色阈值或隐藏特定元素，可直接编辑配置文件： ~/.claude/plugins/claude-hud/config.json

例如，强制启用中文标签：

{
  "language": "zh",
  "lineLayout": "expanded",
  "display.showTools": true,
  "display.showAgents": true
}

修改保存后，重启 Claude Code 即可生效。