claude-hud Review: Finally, a Dashboard for Claude Code

I’ve been using Claude Code for a while and the experience has been solid overall. But one thing has always bugged me — you have no idea what it’s actually doing. It says “analyzing project structure,” but you don’t know how many files it’s read. It says “calling tools,” but you don’t know which ones. It says “a few tasks remaining,” but you have no clue about the actual progress.

This “black box” feeling gets especially obvious when working on large projects. Sometimes you wait five minutes with no response, wondering if it’s stuck or actually working. Then I found claude-hud, a HUD dashboard plugin for Claude Code with 21.7k stars. After installing it, Claude Code’s internal state finally became visible.

What problem does it solve

In short, claude-hud is a “dashboard” for Claude Code. It visualizes the internal runtime state, including:

• Context usage: How many tokens the current conversation has consumed and how close you are to the limit
• Active tools: Which tools Claude is currently calling (file reads, code edits, command execution, etc.)
• Running agents: If sub-agents are running, see each agent’s status and progress
• Todo progress: How many of Claude’s self-assigned todos are done and how many remain

All this information was scattered across Claude Code’s internal state, completely invisible to users. claude-hud aggregates it into a game-like HUD interface that updates in real time.

Core features in practice

Context usage monitoring This is the most practical feature. Claude Code’s context window is limited (currently 200k tokens), and it’s easy to fill up without noticing on large projects. claude-hud shows a progress bar displaying the used/remaining context ratio. It changes color when approaching the limit. I was working on a medium-sized React project and discovered that my conversations were routinely using over 80% of the context by the end — no wonder Claude started “forgetting” things.

Real-time tool call tracking Claude Code frequently calls various tools behind the scenes — read_file, edit_file, run_command, and so on. claude-hud lists these calls in real time with timestamps and execution status. The first time I used it, I was surprised to see Claude making a dozen tool calls just to answer a simple question. This transparency is genuinely helpful for understanding how Claude works.

Agent task board If multi-agent mode is enabled (e.g., having Claude work on multiple files simultaneously), claude-hud gives each agent a card showing its current task, runtime, and output summary. It’s similar to a CI/CD pipeline view — which agent is stuck, which has finished, all at a glance.

Todo progress bar Claude Code has a built-in todo feature that breaks down tasks and tracks progress. claude-hud visualizes this todo list, checking off items as they’re completed and showing overall progress with a progress bar. Especially useful for long tasks — like “refactor type definitions across the entire project” that might take dozens of steps. Seeing progress reduces anxiety.

Real usage scenarios

Scenario 1: Large project onboarding When first importing Claude Code into a large project, it reads files aggressively to build context. Previously you’d just wait blindly. Now through claude-hud, you can see which directories it’s scanning, how many files it’s read, and how much context it’s used. Having expectations makes waiting much less painful.

Scenario 2: Long code generation sessions When asking Claude to generate a complex component or refactor a module, multiple rounds of tool calls are usually needed. claude-hud’s real-time tracking lets me know whether it’s currently reading files, writing code, or running tests. If it’s stuck on a step for too long, I can intervene in time.

Scenario 3: Context management Claude’s performance drops noticeably when context is full. With usage monitoring, I’ve learned to use /clear or start a new conversation at appropriate moments, keeping context within a healthy range.

Quick start

# Install (requires Claude Code to be installed)
npm install -g claude-hud

# Start HUD in a Claude Code session
claude-hud start

# Or enable as a Claude Code plugin
claude config set hud.enabled true

# Customize displayed content
claude-hud config --show-context --show-tools --show-agents --show-todos

The good and the bad

What I loved:

• Actually solves the “black box anxiety” — Claude Code’s process is finally transparent
• Context usage monitoring helped me avoid many cases of “sudden amnesia”
• Clean interface design that doesn’t steal attention, fits nicely in the terminal sidebar
• Very helpful for understanding Claude Code’s internal mechanics
• Todo progress bars significantly reduce the mental burden of long tasks

What frustrated me:

• Installation has quite a few dependencies, npm install pulls in a lot of stuff
• Occasional display lag — the HUD still shows “in progress” after a tool call has finished
• Multi-agent view gets crowded when there are many agents running
• Only supports Claude Code right now, Cursor and Windsurf can’t use it
• Documentation is minimal, some advanced config requires reading source code

Compared to alternatives

There aren’t many tools in the “AI editor state visualization” category. Cursor has a similar output panel built-in, Windsurf has Cascade’s progress display, but neither has the comprehensive dashboard concept that claude-hud offers. If you primarily use Claude Code, this plugin is pretty much essential. If you use other AI editors, their built-in status displays might be sufficient.

Bottom line

claude-hud is one of those “can’t go back after installing” tools. 21.7k stars means plenty of people share the same pain — it’s not that we don’t trust Claude Code, we just don’t like waiting blindfolded. With the dashboard installed, wait times become predictable, intervention timing becomes clear, and the overall experience levels up.

If you’re a heavy Claude Code user, definitely give it a try. It doesn’t change what Claude Code can do — it changes how you understand what Claude Code is doing.

---

About the Author

Liudingyu is a full-stack developer and heavy GitHub user. With 900+ starred repos over the past 3 years, this site only covers tools I’ve actually used or deeply researched.

📧 Found a great tool to recommend? Email [email protected]