claude-hud

Claude HUD — AI Agent 仪表盘

概述

构建实时监控 AI 编码 Agent 的抬头显示仪表盘。跟踪上下文窗口用量、活跃工具调用、子 Agent 状态、任务进度和费用，并通过终端 UI 或 Web 界面呈现。灵感来自 claude-hud（13k+ stars）。

操作说明

步骤 1：了解 HUD 架构

组件	显示内容	数据来源
上下文用量表	已使用 / 剩余令牌数	Agent API 响应头
工具跟踪器	活跃工具调用 + 历史记录	接入工具执行流程
子 Agent 面板	已启动的 Agent + 状态	Agent 编排层
任务进度	待办事项 + 完成情况	解析 Agent 任务列表
费用跟踪器	本次会话的花费	令牌数 x 模型定价

步骤 2：设置项目

mkdir ai-hud && cd ai-hud
npm init -y
npm install blessed blessed-contrib chalk ws

步骤 3：构建上下文用量监视器

// context-monitor.js
class ContextMonitor {
  constructor(maxTokens = 200000) {
    this.maxTokens = maxTokens;
    this.inputTokens = 0;
    this.outputTokens = 0;
    this.cacheHits = 0;
  }
  update(apiResponse) {
    const usage = apiResponse.usage || {};
    this.inputTokens = usage.input_tokens || 0;
    this.outputTokens = usage.output_tokens || 0;
    this.cacheHits = usage.cache_read_input_tokens || 0;
    return this.getStatus();
  }
  getStatus() {
    const total = this.inputTokens + this.outputTokens;
    const pct = ((total / this.maxTokens) * 100).toFixed(1);
    return {
      used: total, remaining: this.maxTokens - total,
      percentage: parseFloat(pct), cached: this.cacheHits,
      warning: parseFloat(pct) > 80 ? 'HIGH' : 'OK'
    };
  }
}

步骤 4：构建工具调用跟踪器

// tool-tracker.js
class ToolTracker {
  constructor() {
    this.active = [];
    this.history = [];
    this.counts = {};
  }
  onToolStart(toolName, input) {
    const call = {
      id: Date.now(), tool: toolName,
      input: JSON.stringify(input).slice(0, 100),
      startedAt: new Date(), status: 'running'
    };
    this.active.push(call);
    this.counts[toolName] = (this.counts[toolName] || 0) + 1;
    return call;
  }
  onToolEnd(callId, output) {
    const idx = this.active.findIndex(c => c.id === callId);
    if (idx !== -1) {
      const call = this.active.splice(idx, 1)[0];
      call.status = 'done';
      call.duration = Date.now() - call.startedAt;
      call.output = String(output).slice(0, 80);
      this.history.unshift(call);
      if (this.history.length > 50) this.history.pop();
    }
  }
  getTopTools(n = 5) {
    return Object.entries(this.counts).sort((a, b) => b[1] - a[1]).slice(0, n);
  }
}

步骤 5：构建终端仪表盘

// dashboard.js
const blessed = require('blessed');
const contrib = require('blessed-contrib');
const screen = blessed.screen({ smartCSR: true, title: 'AI Agent HUD' });
const grid = new contrib.grid({ rows: 12, cols: 12, screen });

const contextGauge = grid.set(0, 0, 3, 4, contrib.gauge, {
  label: ' Context Usage ', stroke: 'green', fill: 'white'
});
const toolLog = grid.set(0, 4, 6, 8, contrib.log, {
  label: ' Tool Calls ', fg: 'green', selectedFg: 'green'
});
const taskBar = grid.set(3, 0, 3, 4, contrib.bar, {
  label: ' Tasks ', barWidth: 6, maxHeight: 10
});
const costLine = grid.set(6, 0, 6, 6, contrib.line, {
  label: ' Cost ($) ', showLegend: true, minY: 0
});
const agentTable = grid.set(6, 6, 6, 6, contrib.table, {
  label: ' Sub-Agents ', keys: true, columnWidth: [20, 10, 15]
});

function refresh(state) {
  contextGauge.setPercent(state.context.percentage);
  state.tools.active.forEach(t => toolLog.log(`> ${t.tool} - ${t.input}`));
  screen.render();
}
screen.key(['escape', 'q', 'C-c'], () => process.exit(0));
screen.render();

步骤 6：通过 WebSocket 连接

// server.js
const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 8765 });

wss.on('connection', (ws) => {
  console.log('HUD client connected');
  ws.on('message', (data) => {
    const event = JSON.parse(data);
    switch (event.type) {
      case 'context_update': contextMonitor.update(event.data); break;
      case 'tool_start': toolTracker.onToolStart(event.tool, event.input); break;
      case 'tool_end': toolTracker.onToolEnd(event.id, event.output); break;
      case 'task_update': taskTracker.update(event.tasks); break;
    }
    broadcastState();
  });
});

步骤 7：添加费用跟踪

const PRICING = {
  'claude-sonnet-4-20250514': { input: 3.0, output: 15.0 },
  'claude-opus-4-20250514': { input: 15.0, output: 75.0 },
  'gpt-4o': { input: 2.5, output: 10.0 },
};

function calculateCost(model, inputTokens, outputTokens) {
  const p = PRICING[model] || PRICING['claude-sonnet-4-20250514'];
  return ((inputTokens * p.input + outputTokens * p.output) / 1_000_000).toFixed(4);
}

示例

示例 1：监控 Claude Code 重构会话

开发者在 Claude Code 重构大型代码库时启动 HUD：

const monitor = new ContextMonitor(200000); // Claude Sonnet 200k context
const tracker = new ToolTracker();

// Simulated events from a real refactoring session
monitor.update({ usage: { input_tokens: 45200, output_tokens: 12800, cache_read_input_tokens: 31000 } });
console.log(monitor.getStatus());
// { used: 58000, remaining: 142000, percentage: 29.0, cached: 31000, warning: 'OK' }

tracker.onToolStart('Read', { file_path: '/src/components/Dashboard.tsx' });
tracker.onToolStart('Grep', { pattern: 'useState', path: '/src' });
tracker.onToolEnd(tracker.active[0].id, '245 lines read');
console.log(tracker.getTopTools());
// [['Read', 12], ['Grep', 8], ['Edit', 6], ['Bash', 3]]
// Dashboard shows: context at 29%, 2 active tools, $0.0234 session cost

示例 2：多 Agent 工作流仪表盘

团队并行运行 3 个 Agent，并在一个 HUD 上监控它们：

const agents = {
  'agent-1-backend': new ContextMonitor(200000),
  'agent-2-frontend': new ContextMonitor(200000),
  'agent-3-tests': new ContextMonitor(200000),
};

// Agent 1: refactoring API routes — 67% context used
agents['agent-1-backend'].update({ usage: { input_tokens: 98000, output_tokens: 36000 } });
// Agent 2: building React components — 23% context used
agents['agent-2-frontend'].update({ usage: { input_tokens: 32000, output_tokens: 14000 } });
// Agent 3: writing test suites — 45% context used
agents['agent-3-tests'].update({ usage: { input_tokens: 61000, output_tokens: 29000 } });

// Dashboard renders 3 gauges side-by-side:
// [agent-1: 67% HIGH] [agent-2: 23% OK] [agent-3: 45% OK]
// Total session cost: $0.0234 + $0.0108 + $0.0179 = $0.0521

指南

• 保持 HUD 轻量 — 避免频繁轮询；使用 WebSocket 推送实时更新
• 将上下文警报设为 80% — 在达到上下文窗口限制前提醒开发者
• 将所有事件记录到磁盘 — 启用会话回放，以便调试和优化
• 支持多个 Agent — 设计仪表盘以处理并行 Agent 工作流
• 按工作流自定义 — 不同任务适合不同的组件布局
• 尊重隐私 — 不要在工具调用历史中记录敏感代码内容；截断输入

参考资料

• jarrodwatts/claude-hud — 最初的灵感来源
• blessed-contrib — 终端仪表盘组件
• Anthropic API usage headers — 令牌计数