Claude HUD is a plugin designed for the Claude Code environment, providing users with real-time insights into their session activity. Its primary purpose is to enhance the user experience by offering a clear and concise overview of the ongoing operations within Claude Code, allowing for better context management, tool tracking, and progress monitoring. The plugin achieves this by displaying a customizable status line below the user's input, offering a "heads-up display" (HUD) of key information.
The core functionality of Claude HUD revolves around providing users with a comprehensive understanding of their context usage. It displays a visual context bar, indicating how full the context window is, and provides percentage-based usage metrics. This feature is crucial for preventing context overflow, which can lead to unexpected behavior or truncated responses from Claude. Furthermore, the plugin integrates with Claude Code's native token data, ensuring accurate and up-to-date context information, unlike estimated values.
Beyond context monitoring, Claude HUD tracks and displays various other aspects of the Claude Code session. It monitors tool activity, showing when Claude is reading, editing, or searching files. This is particularly useful for understanding how Claude is interacting with the user's project and for debugging purposes. The plugin also tracks the status of running agents, displaying which subagents are active and their current tasks. Finally, it provides real-time progress updates for to-do lists, allowing users to monitor task completion within the Claude Code environment.
Installation is straightforward, involving adding the plugin's marketplace and installing the plugin via commands within Claude Code. The plugin also provides setup instructions for Linux and Windows users, addressing potential compatibility issues. Once installed, users can configure the HUD using the `/claude-hud:configure` command, which provides a guided flow for customizing the display. This configuration includes selecting from preset layouts (Full, Essential, Minimal) and toggling individual elements on or off. Advanced users can also manually configure the plugin by editing the `config.json` file, allowing for fine-grained control over colors, display elements, and thresholds.
The plugin offers a range of customization options. Users can control the level of detail displayed, including the project path, git branch information, and subscriber usage limits. The plugin also supports different display formats for context usage, allowing users to choose between percentage, token counts, or remaining tokens. The configuration options extend to the visual appearance of the HUD, with customizable colors for various elements, such as the context bar, model name, and git status.
Claude HUD leverages Claude Code's native statusline API, ensuring seamless integration and compatibility. It updates approximately every 300ms, providing near real-time information. The plugin also includes troubleshooting tips for common issues, such as configuration errors or missing git status information. The plugin requires Claude Code v1.0.80+ and Node.js 18+ or Bun. The project is open-source, licensed under the MIT license, and welcomes contributions.
