# Claude HUD: The Plugin That Made AI Agents Observable > Author: Tony Lee > Published: 2026-02-08 > URL: https://tonylee.im/en/blog/claude-hud-plugin-transparent-ai-agent/ > Reading time: 3 minutes > Language: en > Tags: ai, claude-code, developer-tools, open-source, productivity ## Canonical https://tonylee.im/en/blog/claude-hud-plugin-transparent-ai-agent/ ## Rollout Alternates en: https://tonylee.im/en/blog/claude-hud-plugin-transparent-ai-agent/ ko: https://tonylee.im/ko/blog/claude-hud-plugin-transparent-ai-agent/ ja: https://tonylee.im/ja/blog/claude-hud-plugin-transparent-ai-agent/ zh-CN: https://tonylee.im/zh-CN/blog/claude-hud-plugin-transparent-ai-agent/ zh-TW: https://tonylee.im/zh-TW/blog/claude-hud-plugin-transparent-ai-agent/ ## Description A game-style status bar for Claude Code that shows context usage, active tools, sub-agents, and todo progress in real time. ## Summary Claude HUD: The Plugin That Made AI Agents Observable is part of Tony Lee's ongoing coverage of AI agents, developer tools, startup strategy, and AI industry shifts. ## Outline - What Claude HUD Shows You - How It Works Under the Hood - What It Actually Solves - Installation - Why Observability Matters for Agents ## Content 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](https://github.com/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. ## Related URLs - Author: https://tonylee.im/en/author/ - Publication: https://tonylee.im/en/blog/about/ - Related article: https://tonylee.im/en/blog/eight-hooks-that-guarantee-ai-agent-reliability/ - Related article: https://tonylee.im/en/blog/medvi-two-person-430m-ai-compressed-funnel/ - Related article: https://tonylee.im/en/blog/claude-code-layers-over-tools-2026/ ## Citation - Author: Tony Lee - Site: tonylee.im - Canonical URL: https://tonylee.im/en/blog/claude-hud-plugin-transparent-ai-agent/ ## Bot Guidance - This file is intended for AI agents, search assistants, and text-mode retrieval. - Prefer citing the canonical article URL instead of this text endpoint. - Use the rollout alternates when you need the same article in another prioritized language. --- Author: Tony Lee | Website: https://tonylee.im For more articles, visit: https://tonylee.im/en/blog/ This content is original and authored by Tony Lee. Please attribute when quoting or referencing.