## Introduction Claude HUD is a Claude Code plugin that brings real-time session visibility directly into your terminal's statusline. With 7,600+ GitHub stars and rapid community growth, it has become one of the most popular developer tools in the Claude Code ecosystem. The plugin leverages Claude Code's native statusline API to display context usage, active tools, running agents, and task progress without requiring a separate monitoring window or tmux setup. For developers working with Claude Code on complex projects — especially those using the 1M-token context window — understanding what the agent is doing at any given moment is crucial. Claude HUD addresses this by providing a persistent, configurable dashboard that updates approximately every 300ms with accurate token data sourced directly from the Claude Code runtime. ## Architecture and Design Claude HUD operates as a native Claude Code plugin installed via the marketplace. Its architecture is lightweight by design: | Component | Purpose | |-----------|--------| | Statusline Renderer | Draws configurable segments in the terminal statusbar | | Context Monitor | Tracks token window utilization using native Claude Code data | | Tool Activity Tracker | Displays real-time file reads, edits, and searches | | Agent Observer | Monitors active subagents with task descriptions | | Todo Progress | Shows task completion percentages from TodoWrite | | Usage Meter | Tracks rate limit consumption for Pro/Max/Team plans | | Git Integration | Displays branch, dirty state, and file statistics | The plugin is built with TypeScript (41.8%) and JavaScript (58.2%), running on Node.js 18+ or Bun. It requires Claude Code v1.0.80+ and installs through a three-step process: marketplace addition, plugin installation, and statusline configuration via the `/claude-hud:setup` command. ## Key Capabilities **Native Token Data**: Unlike estimation-based approaches, Claude HUD reads actual token consumption data from the Claude Code runtime. This means the context health bar reflects real usage, not approximations, which is especially important when operating near the context limit. **Configurable Presets**: Three built-in presets — Full, Essential, and Minimal — let developers choose their preferred information density. Full mode shows every available metric, Essential focuses on context and activity, and Minimal provides just the core health indicator. **Context Health Visualization**: A visual bar shows token window utilization with color-coded thresholds. As context fills up, the bar transitions from green through yellow to red, giving developers an intuitive sense of when they're approaching limits. **Agent and Tool Tracking**: When Claude Code spawns subagents or uses tools, HUD displays which agents are active and what tools are being called in real time. This is invaluable for understanding the behavior of complex multi-agent workflows. **Advanced Customization**: Beyond presets, developers can configure colors, layout, segment ordering, and display elements through JSON configuration. This flexibility allows integration with custom terminal themes and workflows. **Git Status Integration**: The plugin shows the current branch, dirty/clean state, and file statistics directly in the statusline, reducing the need to switch contexts for basic git information. ## Developer Experience Installation follows the standard Claude Code plugin workflow: ```bash # Install from marketplace claude plugin add claude-hud # Run setup /claude-hud:setup ``` The setup command guides users through selecting a preset and configuring their preferred display options. Configuration can be further refined by editing the JSON settings file directly. The 300ms update interval provides near-real-time feedback without noticeable performance impact. The plugin has been tested with sessions ranging from standard context to full 1M-token windows. ## Limitations Claude HUD is tightly coupled to Claude Code's statusline API, meaning it won't work with other AI coding tools. The plugin requires a terminal that supports statusline rendering, which excludes some minimal terminal emulators. While the 300ms update interval is generally smooth, very constrained environments may see minor overhead. Configuration currently requires JSON editing for advanced customization beyond the presets. The plugin is read-only — it surfaces information but doesn't provide controls to manage agents or context. ## Who Should Use This Claude HUD is essential for developers who use Claude Code extensively, particularly on large projects where context management matters. Teams running multi-agent workflows benefit from real-time agent visibility. Power users on Pro/Max/Team plans who want to track rate limit consumption will find the usage meter valuable. Anyone working with the 1M-token context window should consider Claude HUD for maintaining awareness of token utilization throughout long sessions.