claude-hud：让 Claude Code 的内心世界一目了然

m0_71614333

424人浏览 · 2026-03-21 10:27:08

m0_71614333 · 2026-03-21 10:27:08 发布

claude-hud：让 Claude Code 的内心世界一目了然

今日 GitHub Trending #1：9,569 stars ⭐ | 当日星增 1,068 | JavaScript

🚀 为什么需要 claude-hud？

在使用 Claude Code 进行 AI 辅助编程时，你是否经常遇到这些困惑：

黑盒操作：不知道 Claude 正在做什么，只能等待结果
上下文焦虑：担心上下文窗口用完，但无法实时查看
工具调用不透明：不清楚 Claude 调用了哪些工具
多 Agent 混乱：多个 Agent 同时运行时难以追踪状态
进度未知：大任务执行时不知道完成度

claude-hud 正是为解决这些问题而生。它是一个Claude Code 插件，提供一个实时 HUD（平视显示器），让你清晰看到 Claude Code 的内部状态。

🎯 核心功能

1️⃣ 上下文使用监控

实时显示 Token 使用情况：

┌─────────────────────────────────┐
│ Context Usage                   │
│ ████████░░░░░░░░░░░░░ 42%       │
│ Used: 81,920 / 200,000 tokens   │
└─────────────────────────────────┘

优势：

✅ 实时追踪：随时了解上下文消耗
✅ 预警机制：接近上限时自动提醒
✅ 优化建议：提示何时需要压缩上下文

2️⃣ 活跃工具显示

查看 Claude 正在使用的工具：

┌─────────────────────────────────┐
│ Active Tools                    │
│ 🔧 exec: npm install            │
│ 📁 read: package.json           │
│ 🔍 search: codebase             │
└─────────────────────────────────┘

特点：

🛠️ 工具列表：清晰展示当前调用的工具
⏱️ 执行时间：显示每个工具的耗时
📊 调用历史：查看过去的工具调用记录

3️⃣ Agent 状态追踪

监控运行中的 Agent：

┌─────────────────────────────────┐
│ Running Agents                  │
│ 🤖 Main Agent    │ ✅ Running    │
│ 🤖 Code Review   │ ⏳ Waiting    │
│ 🤖 Test Runner   │ ✅ Completed  │
└─────────────────────────────────┘

功能：

🎯 状态可视化：每个 Agent 的状态一目了然
🔄 任务队列：查看待执行的任务
📈 性能指标：Agent 执行效率统计

4️⃣ 任务进度展示

实时显示 TODO 列表和进度：

┌─────────────────────────────────┐
│ Task Progress                   │
│ ☑️ 分析需求                      │
│ ☑️ 设计架构                      │
│ 🔄 实现核心功能 (60%)           │
│ ⬜ 编写测试                      │
│ ⬜ 文档更新                      │
└─────────────────────────────────┘

价值：

📋 进度透明：清楚知道任务完成度
🎯 优先级展示：任务优先级排序
✅ 完成追踪：历史记录可回溯

📊 与传统使用方式对比

特性	使用 claude-hud	不使用 claude-hud
上下文可见性	✅ 实时监控	❌ 完全黑盒
工具调用追踪	✅ 详细日志	⚠️ 仅输出结果
Agent 状态	✅ 可视化展示	❌ 无法查看
任务进度	✅ 进度条显示	❌ 未知
调试效率	✅ 快速定位问题	⚠️ 需要猜测
学习成本	✅ 低	⚠️ 需要经验

🛠️ 安装与配置

方式一：通过 Claude Code 插件市场

# 在 Claude Code 中安装
claude install plugin claude-hud

# 验证安装
claude plugins list

方式二：手动安装

# 克隆仓库
git clone https://github.com/jarrodwatts/claude-hud.git
cd claude-hud

# 安装依赖
npm install

# 构建插件
npm run build

# 复制到 Claude Code 插件目录
cp -r dist/* ~/.claude/plugins/claude-hud/

方式三：配置文件

# ~/.claude/config.yaml
plugins:
  claude-hud:
    enabled: true
    settings:
      refresh_rate: 1000  # 刷新频率 (ms)
      show_token_count: true
      show_tool_calls: true
      show_agent_status: true
      position: "top-right"  # HUD 位置
      theme: "dark"  # 主题

💡 实际使用场景

场景一：大型代码重构

任务：重构整个项目的认证模块
     ↓
claude-hud 显示：
┌─────────────────────────────────┐
│ Context: 65% (130k/200k)        │
│ Active: read: auth/*.ts (12)    │
│ Agent: Main ✅ | Test ⏳        │
│ Progress: [██████░░] 60%        │
└─────────────────────────────────┘

价值：实时监控进度，避免上下文溢出

场景二：多文件调试

问题：定位跨文件的 bug
     ↓
claude-hud 追踪：
┌─────────────────────────────────┐
│ Tool Call History               │
│ 1. search: "auth error" (2.3s)  │
│ 2. read: src/auth/login.ts      │
│ 3. read: src/auth/middleware.ts │
│ 4. exec: npm test (running...)  │
└─────────────────────────────────┘

价值：清晰看到 Claude 的调试路径

场景三：长时间任务监控

任务：生成完整的项目文档
     ↓
claude-hud 进度：
┌─────────────────────────────────┐
│ Estimated Time: 8 minutes       │
│ Elapsed: 3 minutes              │
│ Current: Writing API docs       │
│ Next: Writing examples          │
└─────────────────────────────────┘

价值：合理预估等待时间

🔧 技术架构

claude-hud 的核心组件：

┌─────────────────────────────────────────┐
│            claude-hud Plugin            │
├─────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐      │
│  │  Context    │  │    Tool     │      │
│  │  Monitor    │  │   Tracker   │      │
│  └─────────────┘  └─────────────┘      │
│  ┌─────────────┐  ┌─────────────┐      │
│  │   Agent     │  │   Progress  │      │
│  │   Status    │  │   Display   │      │
│  └─────────────┘  └─────────────┘      │
│  ┌─────────────────────────────────┐   │
│  │      Real-time UI Renderer      │   │
│  └─────────────────────────────────┘   │
└─────────────────────────────────────────┘

核心技术：