How Claude‑HUD Turns Claude Code Into a Real‑Time Dashboard

Pain Point

When using Claude Code, developers often encounter context overflow without any visual cue, leading to confused logic and forgotten steps. Manually checking /context is cumbersome, so a real‑time, dashboard‑style status panel is needed.

Project Overview

Claude‑HUD is a high‑star (14K+ stars) open‑source plugin on GitHub, released under the MIT license. It is designed specifically for Claude Code and runs natively in the terminal without requiring extra windows or tmux.

Core Features

Context Monitoring – Shows a visual bar like Context █████░░░░░ 45% with green/yellow/red alerts and token details (over 85% auto‑displayed, data from Claude Code, not estimated).

Subscription Usage – Real‑time sliding‑window consumption (e.g., Usage ██░░░░░░░░ 25% (1h30m / 5h)), 7‑day alerts, visible only to subscribed users.

Tool Activity Tracking – Displays live file operations, e.g., ◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2, to avoid blind waiting.

Agent Status Tracking – Shows sub‑Agent name, model, task, and duration, e.g., ◐ explore [haiku]: Finding auth code (2m15s).

Todo Progress – Shows task completion, e.g., ▸ Fix authentication bug (2/5).

Installation Steps

All steps can be completed in under a minute with three commands:

/plugin marketplace add jarrodwatts/claude-hud

/plugin install claude-hud

/claude-hud:setup

After installation, restart Claude Code for the changes to take effect.

Configuration

Run /claude-hud:configure to launch an interactive guide. Three preset profiles are available: Full – All features enabled, for power users. Essential – Key information balanced with simplicity. Minimal – Only model and context, ultra‑light.

Advanced settings can be edited directly in ~/.claude/plugins/claude-hud/config.json, allowing custom colors, displayed items, and path depth.

Technical Principle

Claude‑HUD leverages Claude Code’s native statusline API. Data flow:

Claude Code → stdin JSON → claude-hud → stdout → terminal display

, with a separate transcript JSON stream for tools, agents, and todos. The panel refreshes roughly every 300 ms and is written in TypeScript with no invasive dependencies.

Common Issues

Usage not shown – Visible only for subscribed accounts; API‑Key login hides it.

Tool/Agent/Todo not displayed – Disabled by default; enable in the configuration.

Git status abnormal on Windows – Re‑run the command to fix.

Configuration not applied – Check JSON syntax; delete and regenerate the config file if needed.

Project URL

https://github.com/jarrodwatts/claude-hud