Claude HUD: The Plugin That Made AI Agents Observable

When a Claude Code session runs a complex multi-step task, the terminal goes quiet. There’s no signal about whether context is nearly exhausted, whether the agent is stuck in a loop, or whether anything is actually happening. You’re left watching a blinking cursor and guessing.

Claude HUD is an open-source plugin that addresses this directly by adding a status bar to the terminal. I’ve been using it for a few weeks and the change in working experience is real, though not without rough edges.

What Claude HUD Shows You

Claude HUD places a status bar at the bottom of your terminal. It tracks four things in real time:

• Context usage: a visual progress bar with percentage showing how much of the session’s context window is consumed
• Active tools: which tools (Read, Edit, Bash, etc.) are currently running
• Sub-agent status: tracks child agents spawned via Task calls (Opus 4.5, Sonnet, etc.)

Todo progress is also surfaced: the bar visualizes completion status of Claude’s internal task list so you can see at a glance how far through a plan the agent is.

How It Works Under the Hood

For those curious about the internals, here’s what’s happening behind the status bar.

Claude Code passes session state directly as a JSON payload via stdin. The plugin calculates context utilization by summing input_tokens, cache_creation_input_tokens, and cache_read_input_tokens, then dividing by context_window_size.

Session logs are processed as a line-by-line stream. The plugin detects tool_use blocks and matches them against tool_result entries to track each tool’s status as running, completed, or errored. For file path display, it extracts file_path from Read, Write, and Edit tool calls, automatically truncates long paths to .../filename.ts format, and refreshes at roughly 300ms intervals.

What It Actually Solves

The plugin addresses a concrete problem: long-running tasks no longer leave you guessing whether the agent is stuck, looping, or about to hit the context limit. In multi-step agent workflows, you can see immediately where things went wrong rather than reconstructing it after the fact.

Three-line installation with no complex configuration makes it easy to try.

Where it falls short: the 300ms refresh rate means very fast tool sequences can be missed in the display, and the sub-agent tracking is incomplete for deeply nested delegation chains. The context bar is the most reliable piece; the tool status display occasionally shows stale state when tool calls overlap.

Installation

Setup takes three commands:

/plugin marketplace add jarrodwatts/claude-hud
/plugin install claude-hud
/claude-hud:setup

GitHub: jarrodwatts/claude-hud

Why Observability Matters for Agents

Knowing when context is about to run out changes how you structure long sessions. You can checkpoint work earlier, split tasks more deliberately, and avoid the frustrating experience of an agent losing coherence 80% through a large task because you didn’t notice the context bar was at 95%.

Observability is a standard expectation for servers and pipelines. AI agents that run for minutes at a time need it too, and most tooling hasn’t caught up yet.