claude-hud

Claude HUD — AI エージェントダッシュボード

概要

AI コーディングエージェントをリアルタイムで監視する HUD ダッシュボードを構築します。コンテキストウィンドウの使用量、実行中のツール呼び出し、サブエージェントの状態、タスクの進捗、コストを追跡し、すべてターミナル UI またはウェブインターフェースに表示します。claude-hud（13k 以上のスター）に着想を得ています。

手順

ステップ 1：HUD のアーキテクチャを理解する

コンポーネント	表示内容	データソース
コンテキストメーター	使用済み／残りのトークン数	エージェント API のレスポンスヘッダー
ツールトラッカー	実行中のツール呼び出しと履歴	ツール実行にフック
サブエージェントパネル	起動されたエージェントと状態	エージェントのオーケストレーション層
タスクの進捗	ToDo 項目と完了状況	エージェントのタスクリストを解析
コストトラッカー	このセッションでの支出額（$）	トークン数 × モデルの料金

ステップ 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 によるリファクタリングセッションを監視する

開発者が HUD を起動し、Claude Code が大規模なコードベースをリファクタリングします。

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：マルチエージェントのワークフローダッシュボード

チームが 3 つのエージェントを並行して実行し、1 つの 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% に設定する — コンテキストウィンドウの上限に達する前に開発者へ警告します
• すべてのイベントをディスクに記録する — デバッグと最適化のため、セッションの再生を可能にします
• 複数のエージェントをサポートする — 並列エージェントのワークフローを処理できるようにダッシュボードを設計します
• ワークフローごとにカスタマイズする — タスクによって最適なウィジェットのレイアウトは異なります
• プライバシーを尊重する — ツール呼び出し履歴に機密性の高いコード内容を記録せず、入力を切り詰めます

参考資料

• jarrodwatts/claude-hud — 着想元
• blessed-contrib — ターミナルダッシュボード用ウィジェット
• Anthropic API usage headers — トークン数のカウント