Claude HUD: A Statusline Plugin That Makes Claude Code's Inner Workings Visible

The Problem: Claude Code Sessions Are a Black Box

When you run a long Claude Code session, the assistant works through files, calls tools, spawns subagents, and consumes context. The terminal gives you the conversation text, but not the surrounding state. You cannot see how full the context window is until you hit a limit. You cannot tell which subagent is doing what or whether a todo item is progressing. Claude HUD addresses this by putting that state directly into the statusline, the area below your input. It is for developers who run multi-hour sessions, manage complex tasks with subagents, or need to monitor rate limits. The plugin does not add a new window or require tmux. It uses the statusline that Claude Code already renders, which keeps the overhead low and the integration tight.

How It Works: Statusline API and Transcript Parsing

Claude HUD has two data sources. The first is the native statusline API, which provides token counts and context window size directly from Claude Code. The README states these are native token data, not estimated. The second source is the transcript JSONL file, which records tool calls, agent activity, and todo updates. The plugin parses this file to extract events. The data flow is: Claude Code sends stdin JSON to the plugin, the plugin processes it, and the output is written to stdout, which the terminal displays. Re-rendering happens after each interaction, including new assistant messages, /compact, permission changes, and vim-mode toggles. The render is debounced at 300ms, so it does not repaint on every keystroke. This design means the HUD reflects the session state in near real time, but it depends on the transcript being written correctly. If Claude Code changes the transcript format, the plugin may need updates.

Installation: Marketplace, Plugin, and Setup Commands

Installation is done inside a Claude Code session. First, add the marketplace with /plugin marketplace add jarrodwatts/claude-hud. Then install the plugin with /plugin install claude-hud. After that, run /reload-plugins to activate it without restarting. The README notes that older Claude Code versions may require a full restart to pick up statusLine changes. For terminal users, the same steps work via the CLI: claude plugin marketplace add jarrodwatts/claude-hud and claude plugin install claude-hud@claude-hud. Then run /reload-plugins inside the session. The final step is /claude-hud:setup, which configures the statusline. On Windows, the setup may fail if no JavaScript runtime is found; the README instructs installing Node.js LTS via winget install OpenJS.NodeJS.LTS. On Linux, older Claude Code versions can hit an EXDEV error during installation because /tmp is a separate filesystem. The fix is to update Claude Code, or set TMPDIR to a directory on the same filesystem and start claude from there.

Configuration: Presets, Manual Edits, and Multi-Directory Support

The plugin offers a guided configuration flow via /claude-hud:configure. This flow handles layout, language, and common display toggles. It also offers three presets: Full, Essential, and Minimal. Full enables everything: tools, agents, todos, git, usage, and duration. Essential shows activity lines plus git status, with minimal clutter. Minimal shows only the model name and context bar. After choosing a preset, you can toggle individual elements. For advanced settings, you edit ~/.claude/plugins/claude-hud/config.json directly. This file supports keys like colors.*, pathLevels, maxWidth, threshold overrides, display.timeFormat, display.hourCycle, and display.promptCacheTtlSeconds. The guided flow preserves those manual settings while letting you change language and layout. A notable feature is support for multiple Claude config directories. If you use CLAUDE_CONFIG_DIR and symlink the plugins directory, the config file is shared. To have per-directory settings, you create a claude-hud.json file in each config directory, which layers on top of the shared config. The example shows { "display": { "customLine": "Work Team" } }. This is a thoughtful design for users who run separate work and personal environments.

What the HUD Displays: Context Bars, Tool Activity, and Agent Status

The default two-line HUD shows the model name, provider label when identified (such as Bedrock, Vertex, MiniMax), project path, and git branch on the first line. The second line shows a context bar that fills as you use context, with color shifting from green to yellow to red, and a usage bar with time remaining, for example (1h 30m / 5h). Optional lines show tool activity like Edit: auth.ts or Read x3, agent status with the subagent model and task, and todo progress with a counter like (2/5). The context bar scales with Claude Code's reported context window size, including 1M-context sessions. This is a practical feature because context limits are a common failure point in long sessions. The tool activity line updates as the assistant reads, edits, and greps files, which gives you a sense of what the model is doing even when it is silent. The agent tracking line shows which subagent is running and for how long, which is useful when you spawn multiple agents.

Limitations and Failure Modes

The plugin depends on the statusline API and the transcript JSONL file. If Claude Code changes either of those, the HUD may break. The README does not mention a fallback if the transcript is unavailable or corrupted. Another limitation is that the HUD only appears in the statusline, so it is not visible when you scroll through past output or when the terminal is resized. The width detection can fail; the plugin has a maxWidth option as a fallback, but it is only used when terminal width detection fails completely. If you set forceMaxWidth, the plugin always uses maxWidth, which can truncate content if you set it too small. The plugin also adds a small overhead to every interaction because it re-parses the transcript after each event, debounced at 300ms. For very long sessions, the transcript file can grow large, and parsing it repeatedly might cause noticeable latency, though the README does not provide performance numbers. The plugin is not a substitute for a full observability tool; it shows a snapshot, not a history.

Alternatives: Native Statusline vs. External Monitors

The closest alternative is to use Claude Code's built-in statusline without a plugin. You can configure the statusLine field in your settings to show model, context, and other data using Claude Code's own variables. That approach is simpler and has no third-party dependency, but it does not parse the transcript for tool or agent activity. It gives you token counts and basic session info, but not the granular activity lines that Claude HUD adds. Another alternative is to run a separate terminal or tmux pane that tails the transcript JSONL file with a tool like jq or a custom script. That gives you full control and can show historical data, but it requires manual setup and does not integrate with the statusline. Claude HUD sits between those: it uses the native API for token data and adds transcript parsing for activity, all in the statusline. If you already have a custom statusline setup, Claude HUD may conflict with it, since it overwrites the statusLine setting.

Maintenance and License Considerations

The project is MIT licensed, which means you can use, modify, and redistribute it freely, including in commercial products. The repository shows active development, with recent releases in August 2026, including v0.8.0. The README mentions a fix for a Claude Code bug related to EXDEV, which suggests the maintainer tracks upstream changes. However, the plugin's reliance on internal transcript formats means it may need frequent updates as Claude Code evolves. If you fork it, you take on that maintenance burden. The config file format is stable, but the parsing logic is tied to specific event shapes. The README does not document a migration path for config files across major versions. For a plugin, the upgrade cost is low: you reinstall the plugin and run /reload-plugins. But you should check the changelog for each release to see if the transcript parsing changed. The plugin also supports multiple languages, which adds a small translation layer, but that is not a maintenance concern for most users.

Editorial conclusion

Adopt Claude HUD if you spend long sessions in Claude Code and need real-time awareness of context consumption, tool calls, and subagent progress. It is a good fit for developers who want a lightweight, terminal-native overlay without switching to a GUI or tmux. Avoid it if you rarely exceed short interactions or if you prefer a minimal interface, since the default two-line HUD adds visual noise. Before adopting, verify that your Claude Code version supports the statusline API and that plugin installation works on your platform, especially on Linux with older versions where EXDEV errors can occur. Also check that your terminal width detection works, or set maxWidth explicitly. The plugin is MIT-licensed, so you can fork and modify it freely, but you must maintain your fork yourself if you do.

Official sources

1. Official README
2. Project repository
3. Release notes