Claude HUD

技能由 ara.so 提供 — 每日 2026 技能合集。

Claude HUD 是一个 Claude Code 插件，可在终端中添加持久状态行，实时显示上下文窗口使用情况、活跃工具调用、运行中的子代理和待办事项进度——始终显示在输入提示下方。

功能

特性	描述
上下文健康度	显示上下文窗口使用率的可视化条（绿色 → 黄色 → 红色）
工具活动	实时显示文件读取、编辑和搜索操作
代理跟踪	显示正在运行的子代理及其当前任务
待办进度	实时任务完成跟踪
使用限制	Claude 订阅者速率限制消耗
Git 状态	当前分支、脏状态、与远程的领先/落后

要求

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

安装

在 Claude Code 会话中运行以下命令：

步骤 1：添加市场

/plugin marketplace add jarrodwatts/claude-hud

步骤 2：安装插件

/plugin install claude-hud

Linux 用户：如果遇到 EXDEV: cross-device link not permitted，请先设置 TMPDIR：
mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude

步骤 3：配置状态行

/claude-hud:setup

Windows 用户：如果设置报告没有 JavaScript 运行时，请先安装 Node.js LTS：
winget install OpenJS.NodeJS.LTS

步骤 4：重启 Claude Code 以加载新的 statusLine 配置。

显示效果

默认双行布局

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

启用可选行后

[Opus] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)
◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2
◐ explore [haiku]: Finding auth code (2m 15s)
▸ Fix authentication bug (2/5)

配置

交互式配置（推荐）

/claude-hud:configure

这将打开一个引导流程，提供预设选项：

预设	显示内容
完整	全部——工具、代理、待办、git、使用情况、持续时间
基本	活动行 + git，最小化杂乱
极简	仅模型名称和上下文条

手动配置

直接编辑 ~/.claude/plugins/claude-hud/config.json：

{
  "lineLayout": "expanded",
  "pathLevels": 2,
  "elementOrder": ["project", "context", "usage", "tools", "agents", "todos"],
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": false
  },
  "display": {
    "showModel": true,
    "showContextBar": true,
    "contextValue": "percent",
    "showUsage": true,
    "usageBarEnabled": true,
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showDuration": false,
    "showSpeed": false,
    "showConfigCounts": false,
    "showMemoryUsage": false,
    "showSessionName": false,
    "showClaudeCodeVersion": false,
    "sevenDayThreshold": 80,
    "showTokenBreakdown": true
  },
  "colors": {
    "context": "green",
    "usage": "brightBlue",
    "warning": "yellow",
    "usageWarning": "brightMagenta",
    "critical": "red",
    "model": "cyan",
    "project": "yellow",
    "git": "magenta",
    "gitBranch": "cyan",
    "label": "dim",
    "custom": "208"
  }
}

关键配置选项

布局

{
  "lineLayout": "expanded",   // "expanded"（多行）或 "compact"（单行）
  "pathLevels": 1             // 项目路径中的目录层级数 1-3
}

路径层级示例：

1 → [Opus] │ my-project git:(main)
2 → [Opus] │ apps/my-project git:(main)
3 → [Opus] │ dev/apps/my-project git:(main)

上下文显示格式

{
  "display": {
    "contextValue": "percent"    // "45%"
    // "contextValue": "tokens"  // "45k/200k"
    // "contextValue": "remaining" // "55% remaining"
    // "contextValue": "both"    // "45% (45k/200k)"
  }
}

元素顺序（展开布局）

{
  "elementOrder": ["project", "context", "usage", "memory", "environment", "tools", "agents", "todos"]
}

从数组中省略任何条目即可完全隐藏。

Git 状态选项

{
  "gitStatus": {
    "enabled": true,
    "showDirty": true,         // 未提交更改时显示 "main*"
    "showAheadBehind": true,   // "main ↑2 ↓1"
    "showFileStats": true      // "main* !3 +1 ?2"（已修改/已添加/已删除/未跟踪）
  }
}

颜色

支持的值：命名颜色（dim, red, green, yellow, magenta, cyan, brightBlue, brightMagenta）、256 色数字（0-255）或十六进制（#rrggbb）。

{
  "colors": {
    "context": "#00FF88",
    "model": "208",
    "project": "#FF6600"
  }
}

工作原理

Claude HUD 使用 Claude Code 的原生 statusline API——无需单独窗口，无需 tmux：

Claude Code → stdin JSON → claude-hud → stdout → 终端状态行
           ↘ 转录 JSONL（实时解析工具、代理、待办）

Token 数据直接来自 Claude Code（非估算）
根据报告的上下文窗口大小（包括 1M 上下文会话）进行缩放
解析转录以获取工具/代理活动
每约 300ms 更新一次

常见模式

专注工作的极简设置

{
  "lineLayout": "compact",
  "display": {
    "showModel": true,
    "showContextBar": true,
    "contextValue": "percent",
    "showUsage": false,
    "showTools": false,
    "showAgents": false,
    "showTodos": false
  }
}

完整监控设置

{
  "lineLayout": "expanded",
  "pathLevels": 2,
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": true
  },
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showDuration": true,
    "showMemoryUsage": true,
    "showConfigCounts": true,
    "contextValue": "both",
    "showTokenBreakdown": true
  }
}

始终显示 7 天使用情况

{
  "display": {
    "showUsage": true,
    "sevenDayThreshold": 0
  }
}

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

故障排除

设置后 HUD 未显示

完全重启 Claude Code（退出并在终端中重新运行 claude）
在 macOS 上，确保完全退出应用，而不仅仅是关闭窗口

配置未生效

检查 JSON 语法错误——无效 JSON 会静默回退到默认值
验证：cat ~/.claude/plugins/claude-hud/config.json | node -e "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'))"
删除配置并运行 /claude-hud:configure 重新生成

Git 状态缺失

确认你在 git 仓库中（git status）
确保配置中 gitStatus.enabled 不是 false

工具/代理/待办行未显示

这些默认隐藏——通过 showTools、showAgents、showTodos 启用
仅在有活动时才会渲染行

使用限制未显示

需要 Claude 订阅账户（不仅仅是 API 密钥）
AWS Bedrock 用户看到 Bedrock 标签；使用情况在 AWS 控制台中管理
在新会话中，使用数据可能为空，直到第一个模型响应后
较旧的 Claude Code 版本不发出 rate_limits，因此不会显示订阅者使用情况

Linux 安装时跨设备错误

mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude
# 然后在该会话中运行 /plugin install claude-hud

Windows：未找到 JavaScript 运行时

winget install OpenJS.NodeJS.LTS
# 重启 shell，然后再次运行 /claude-hud:setup

插件命令参考

命令	描述
`/plugin marketplace add jarrodwatts/claude-hud`	注册插件源
`/plugin install claude-hud`	安装插件
`/claude-hud:setup`	初始设置向导，写入 `statusLine` 配置
`/claude-hud:configure`	交互式配置，带预览

配置文件位置

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

claude-hud-statusline

相关 Skills