jarrodwatts/claude-hud

# Claude HUD 一个用于显示 Claude Code 当前状态的插件——包括上下文使用情况、活跃工具、运行中的 agent 以及待办事项进度。始终显示在你的输入框下方。 [](LICENSE) [](https://github.com/jarrodwatts/claude-hud/stargazers)  ## 安装 在 Claude Code 实例中，运行以下命令： **步骤 1：添加市场源** ``` /plugin marketplace add jarrodwatts/claude-hud ``` **步骤 2：安装插件**

⚠️ Linux 用户：请先点击这里

在 Linux 上，`/tmp` 通常是一个独立的文件系统 (tmpfs)，这会导致插件安装失败并显示： ``` EXDEV: cross-device link not permitted ``` **解决方法**：在安装前设置 TMPDIR： ``` mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude ``` 然后在该会话中运行下方的安装命令。这是一个 [Claude Code 平台限制](https://github.com/anthropics/claude-code/issues/14799)。

``` /plugin install claude-hud ``` **步骤 3：配置状态栏** ``` /claude-hud:setup ``` 完成！HUD 会立即出现——无需重启。 ## Claude HUD 是什么？ Claude HUD 让你更深入地了解 Claude Code 会话中发生的事情。 | 你看到的 | 为什么重要 | |--------------|----------------| | **项目路径** | 知道你在哪个项目中（可配置显示 1-3 级目录） | | **上下文健康度** | 在为时已晚之前，准确了解你的上下文窗口有多满 | | **工具活动** | 实时查看 Claude 读取、编辑和搜索文件的操作 | | **Agent 追踪** | 查看哪些子 agent 正在运行以及它们在做什么 | | **待办进度** | 实时追踪任务完成情况 | ## 你能看到什么 ### 默认（2 行） ``` [Opus | Max] │ my-project git:(main*) Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h) ``` - **第 1 行** — 模型、计划名称（或 `Bedrock`）、项目路径、git 分支 - **第 2 行** — 上下文条（绿 → 黄 → 红）和使用率限制 ### 可选行（通过 `/claude-hud:configure` 启用） ``` ◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2 ← Tools activity ◐ explore [haiku]: Finding auth code (2m 15s) ← Agent status ▸ Fix authentication bug (2/5) ← Todo progress ``` ## 工作原理 Claude HUD 使用 Claude Code 原生的 **statusline API**——无需单独窗口，无需 tmux，可在任何终端中工作。 ``` Claude Code → stdin JSON → claude-hud → stdout → displayed in your terminal ↘ transcript JSONL (tools, agents, todos) ``` **关键特性：** - 来自 Claude Code 的原生 token 数据（非估算） - 根据 Claude Code 报告的上下文窗口大小进行缩放，包括较新的 1M 上下文会话 - 解析 transcript 以获取工具/agent 活动 - 约每 300ms 更新一次 ## 配置 随时自定义你的 HUD： ``` /claude-hud:configure ``` 引导流程会处理布局和显示开关。高级覆盖设置（如自定义颜色和阈值）会在那里保留，但你需要通过直接编辑配置文件来设置它们： - **首次设置**：选择一个预设（完整/精简/最小），然后微调各个元素 - **随时自定义**：开关各项、调整 git 显示样式、切换布局 - **保存前预览**：在提交更改前查看 HUD 的确切外观 ### 预设 | 预设 | 显示内容 | |--------|--------------| | **Full（完整）** | 启用所有内容——工具、agent、待办、git、使用量、时长 | | **Essential（精简）** | 活动行 + git 状态，信息杂乱度最低 | | **Minimal（最小）** | 仅核心——仅显示模型名称和上下文条 | 选择预设后，你可以单独开启或关闭各个元素。 ### 手动配置 直接编辑 `~/.claude/plugins/claude-hud/config.json` 以进行高级设置，如 `colors.*`、`pathLevels` 和阈值覆盖。运行 `/claude-hud:configure` 将保留这些手动设置。 ### 选项 | 选项 | 类型 | 默认值 | 描述 | |--------|------|---------|-------------| | `lineLayout` | string | `expanded` | 布局：`expanded`（多行）或 `compact`（单行） | | `pathLevels` | 1-3 | 1 | 项目路径中显示的目录层级数 | | `elementOrder` | string[] | `["project","context","usage","environment","tools","agents","todos"]` | 展开模式下的元素顺序。省略条目即可在展开模式下隐藏它们。 | | `gitStatus.enabled` | boolean | true | 在 HUD 中显示 git 分支 | | `gitStatus.showDirty` | boolean | true | 对未提交的更改显示 `*` | | `gitStatus.showAheadBehind` | boolean | false | 显示 `↑N ↓N` 表示领先/落后于远程 | | `gitStatus.showFileStats` | boolean | false | 显示文件更改计数 `!M +A ✘D ?U` | | `display.showModel` | boolean | true | 显示模型名称 `[Opus]` | | `display.showContextBar` | boolean | true | 显示可视化上下文条 `████░░░░░░` | | `display.contextValue` | `percent` \| `tokens` \| `remaining` | `percent` | 上下文显示格式（`45%`、`45k/200k` 或剩余 `55%`） | | `display.showConfigCounts` | boolean | false | 显示 CLAUDE.md、rules、MCPs、hooks 计数 | | `display.showDuration` | boolean | false | 显示会话时长 `⏱️ 5m` | | `display.showSpeed` | boolean | false | 显示输出 token 速度 `out: 42.1 tok/s` | | `display.showUsage` | boolean | true | 显示使用限制（仅限 Pro/Max/Team） | | `display.usageBarEnabled` | boolean | true | 将使用量显示为可视化条而非文本 | | `display.sevenDayThreshold` | 0-100 | 80 | 当 >= 阈值时显示 7 天使用量（0 = 始终显示） | | `display.showTokenBreakdown` | boolean | true | 在高上下文（85%+）时显示 token 详情 | | `display.showTools` | boolean | false | 显示工具活动行 | | `display.showAgents` | boolean | false | 显示 agents 活动行 | | `display.showTodos` | boolean | false | 显示待办进度行 | | `display.showSessionName` | boolean | false | 显示来自 `/rename` 的会话 slug 或自定义标题 | | `usage.cacheTtlSeconds` | number | 60 | 缓存成功使用量 API 响应的时长（秒） | | `usage.failureCacheTtlSeconds` | number | 15 | 重试前缓存失败使用量 API 响应的时长（秒） | | `colors.context` | color name | `green` | 上下文条和上下文百分比的基础颜色 | | `colors.usage` | color name | `brightBlue` | 低于警告阈值的使用量条和百分比的基础颜色 | | `colors.warning` | color name | `yellow` | 上下文阈值和使用量警告文本的警告颜色 | | `colors.usageWarning` | color name | `brightMagenta` | 接近阈值的使用量条和百分比的警告颜色 | | `colors.critical` | color name | `red` | 达到限制状态和临界阈值的严重颜色 | 支持的颜色名称：`red`、`green`、`yellow`、`magenta`、`cyan`、`brightBlue`、`brightMagenta`。 ### 使用限制 (Pro/Max/Team) 使用量显示默认为 Claude Pro、Max 和 Team 订阅者**启用**。它在第 2 行上下文条旁边显示你的速率限制消耗。 当高于 `display.sevenDayThreshold`（默认 80%）时，会显示 7 天百分比： ``` Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h) | ██████████ 85% (2d / 7d) ``` 要禁用，请将 `display.showUsage` 设置为 `false`。 **要求：** - Claude Pro、Max 或 Team 订阅（API 用户不可用） - 来自 Claude Code 的 OAuth 凭证（登录时自动创建） **故障排除：** 如果使用量未显示： - 确保你使用 Pro/Max/Team 账户登录（而非 API key） - 检查配置中 `display.showUsage` 未设置为 `false` - API 用户看不到使用量显示（他们是按 token 付费，而非速率限制） - AWS Bedrock 模型显示 `Bedrock` 并隐藏使用限制（用量在 AWS 中管理） - 非默认的 `ANTHROPIC_BASE_URL` / `ANTHROPIC_API_BASE_URL` 设置会跳过使用量显示，因为 Anthropic OAuth 使用量 API 可能不适用 - 如果你在代理后面，请设置 `HTTPS_PROXY`（或 `HTTP_PROXY`/`ALL_PROXY`）以及可选的 `NO_PROXY` - 对于高延迟环境，请使用 `CLAUDE_HUD_USAGE_TIMEOUT_MS`（毫秒）增加使用量 API 超时时间 ### 配置示例 ``` { "lineLayout": "expanded", "pathLevels": 2, "elementOrder": ["project", "tools", "context", "usage", "environment", "agents", "todos"], "gitStatus": { "enabled": true, "showDirty": true, "showAheadBehind": true, "showFileStats": true }, "display": { "showTools": true, "showAgents": true, "showTodos": true, "showConfigCounts": true, "showDuration": true }, "colors": { "context": "cyan", "usage": "cyan", "warning": "yellow", "usageWarning": "magenta", "critical": "red" }, "usage": { "cacheTtlSeconds": 120, "failureCacheTtlSeconds": 30 } } ``` ### 显示示例 **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` **工具/agent/待办行缺失？** - 这些默认隐藏——在配置中使用 `showTools`、`showAgents`、`showTodos` 启用 - 它们也仅在有活动可显示时出现 ## 系统要求 - 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](CONTRIBUTING.md) 了解指南。 ## 许可证 MIT — 详见 [LICENSE](LICENSE) ## Star 历史 [](https://star-history.com/#jarrodwatts/claude-hud&Date)

标签：AI 编程助手, Anthropic Claude, Claude Code 插件, DevEx, Homebrew安装, HUD, IDE 扩展, MITM代理, Todo 列表, Token 使用量, 上下文监控, 任务进度, 威胁情报, 工具活动追踪, 平视显示器, 开发体验, 开发者工具, 智能体追踪, 状态栏, 生产效率, 终端用户界面, 自定义脚本, 资源监控