How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/TerminalSkills/skills --skill claude-hudBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
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
bash
mkdir ai-hud && cd ai-hud
npm init -y
npm install blessed blessed-contrib chalk wsStep 3: Build the Context Usage Monitor
javascript
// 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
javascript
// 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
javascript
// 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
javascript
// 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
javascript
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:
javascript
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 costExample 2: Multi-Agent Workflow Dashboard
A team runs 3 agents in parallel and monitors all of them on one HUD:
javascript
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.0521Guidelines
- 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
