claude-hud

name claude-hud description Build heads-up display (HUD) dashboards for AI coding agents — show context usage, active tools, running sub-agents, and task progress in real-time. Use when: monitoring AI agent activity, building developer tools for AI-assisted coding, creating status dashboards for agent workflows. license MIT compatibility Claude Code, Node.js 18+ metadata {"author":"terminal-skills","version":"1.0.0","category":"development","tags":["claude-code","hud","dashboard","devtools","monitoring"],"use-cases":["Build a real-time dashboard showing what your AI agents are doing","Monitor context window usage and tool calls during AI coding sessions","Create a progress tracker for multi-step AI agent workflows"],"agents":["claude-code","openai-codex","gemini-cli","cursor"]} Claude HUD — AI Agent Dashboard Overview Build heads-up display dashboards that monitor AI coding agents in real-time. Track context window consumption, active tool calls, sub-agent status, task progress, and cost — all rendered in a terminal UI or web interface. Inspired by claude-hud (13k+ stars). Instructions Step 1: Understand the HUD Architecture Component What It Shows Data Source Context meter Tokens used / remaining Agent API response headers Tool tracker Active tool calls + history Hook into tool execution Sub-agent panel Spawned agents + status Agent orchestration layer Task progress Todo items + completion Parse agent task lists Cost tracker $ spent this session Token count x model pricing Step 2: Set Up the Project mkdir ai-hud && cd ai-hud npm init -y npm install blessed blessed-contrib chalk ws Step 3: Build the Context Usage Monitor // 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' }; } } Step 4: Build the Tool Call Tracker // 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); } } Step 5: Build the Terminal Dashboard // 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 (); Step 6: Connect via 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 (); }); }); Step 7: Add Cost Tracking 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 ); } Examples Example 1: Monitor a Claude Code Refactoring Session A developer launches the HUD while Claude Code refactors a large codebase: 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 Example 2: Multi-Agent Workflow Dashboard A team runs 3 agents in parallel and monitors all of them on one 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 Guidelines Keep the HUD lightweight — avoid heavy polling; use WebSocket push for real-time updates Set context alerts at 80% — warn developers before hitting the context window limit Log all events to disk — enable session replay for debugging and optimization Support multiple agents — design the dashboard to handle parallel agent workflows Customize per workflow — different tasks benefit from different widget layouts Respect privacy — do not log sensitive code content in tool call history; truncate inputs References jarrodwatts/claude-hud — original inspiration blessed-contrib — terminal dashboard widgets Anthropic API usage headers — token counting