# Claude HUD: a statusline plugin that shows context, tools and agents in Claude Code

> Claude HUD is a Claude Code plugin that renders a statusline below your input, showing context usage, active tools, running agents and todo progress. It installs from a plugin marketplace and needs Node.js for the setup step, but it depends on Claude Code's statusline API and transcript format.

**jarrodwatts/claude-hud** — A Claude Code plugin that shows what's happening - context usage, active tools, running agents, and todo progress.

- Repository: https://github.com/jarrodwatts/claude-hud
- Stars: 28,167 · Forks: 1,306
- Language: JavaScript
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/jarrodwatts-claude-hud

## The problem Claude HUD addresses inside a Claude Code session

A Claude Code session hides most of its own state. The context window fills up, subagents start and finish, tools run in sequence, and the todo list advances, but the only surface for that information is the conversation itself. The README frames the plugin as a way to see "context usage, active tools, running agents, and todo progress" always visible below the input, which is a narrow and specific goal: it is a display layer, not an agent framework, not a proxy, not a logging service.

The audience is therefore people who already live in Claude Code and have hit the point where a long session surprises them. The README lists the concrete items: project path with configurable 1 to 3 directory levels, a context health bar, tool activity, agent tracking, and todo completion. If you never run long sessions, or you work through a wrapper that already prints this state, the plugin adds a line of text you will not read.

One design decision stands out. The plugin does not estimate context usage; the README states it uses "native token data from Claude Code" and scales with the reported context window size, including 1M-context sessions. That matters because a guessed percentage is worse than no percentage: it teaches you to ignore the bar.

## How the statusline pipeline works: stdin JSON in, rendered line out

Claude HUD is a statusline renderer. The README gives the data flow explicitly: Claude Code writes stdin JSON to the plugin, the plugin writes stdout, and the terminal displays it. A second input, the transcript JSONL, is parsed for tool, agent and todo activity. There is no daemon, no separate window and no tmux requirement.

That architecture explains the visible behaviour. Because the plugin is invoked by Claude Code's statusline API, it re-renders after each interaction: new assistant messages, /compact, permission changes and vim-mode toggles, debounced at 300ms according to the README. The debounce is the interesting part. A statusline process that re-runs on every event would spawn constantly, so a 300ms window trades a little latency for fewer process starts. The README does not document what happens if a render takes longer than the debounce window, and it does not describe a queue.

The default output is two lines. The first carries the model, a provider label when positively identified (the README names Bedrock, Vertex and MiniMax as examples), the project path and the git branch. The second carries the context bar and the usage rate limits. Optional lines add tool activity, agent status and todo progress. The context bar changes colour from green to yellow to red, which is the only part of the display that encodes a judgement rather than a fact.

Everything the plugin shows comes from data Claude Code already produces. It does not instrument tool calls itself, so a tool that Claude Code does not surface in the transcript will not appear.

## Installing Claude HUD and getting the first HUD line

Installation happens inside a Claude Code instance. The README gives three steps: add the marketplace, install the plugin, then configure the statusline. The first two commands are plugin commands.

```bash
/plugin marketplace add jarrodwatts/claude-hud
/plugin install claude-hud
```

After the install command, the README says to reload plugins rather than restart the session.

```bash
/reload-plugins
```

The same two steps can be done outside a session with the Claude Code CLI, according to the README's terminal section.

```bash
claude plugin marketplace add jarrodwatts/claude-hud
claude plugin install claude-hud@claude-hud
```

Then the statusline has to be wired up. The README's step 3 is a namespaced command, and it is the step that needs a JavaScript runtime.

```bash
/claude-hud:setup
```

After setup, the README states that Claude Code reloads settings automatically and the HUD appears after the next message. If it does not appear, the README says to restart Claude Code, because older versions only pick up statusLine changes on restart. On Windows the supported runtime for setup is Node.js LTS; if setup reports no JavaScript runtime, the README gives a winget install and asks you to restart the shell before running setup again.

```powershell
winget install OpenJS.NodeJS.LTS
```

What you should see is the two-line default: model and branch on the first line, a context bar and usage rate limits on the second.

## Linux EXDEV failures and the TMPDIR workaround

The README documents one install failure in detail, and it is worth reading before you file a bug. On older Claude Code versions, /tmp being a separate filesystem (tmpfs) made plugin installation fail with EXDEV: cross-device link not permitted. The README attributes this to a Claude Code bug (anthropics/claude-code issue 14799) that it says has since been fixed, and tells you to update Claude Code first.

If you cannot update, the README's workaround is to point TMPDIR at a directory on the same filesystem as the plugin location before starting the session.

```bash
mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude
```

The install command then runs in that session. This is a fair example of the plugin's dependency posture: the failure is not in the plugin's own code, it is in how Claude Code moves plugin files across filesystems. The README does not describe rollback or uninstall steps for a half-installed plugin, so if the install fails partway you are relying on Claude Code's own plugin management.

The same section is a reminder that the plugin's compatibility surface is Claude Code itself. Anything that changes how plugins are staged, or how the statusline is invoked, lands on this project.

## Configuring the HUD: presets, the guided flow and the config file

Configuration is split between a guided flow and a file. The guided flow is a slash command.

```bash
/claude-hud:configure
```

The README says the first run asks you to choose a preset (Full, Essential or Minimal), pick a label language, and then fine-tune individual elements, with a preview before saving. Full enables tools, agents, todos, git, usage and duration. Essential keeps activity lines plus git status. Minimal is model name and context bar only. The guided flow also handles layout, language and common display toggles.

Advanced settings are edited directly in ~/.claude/plugins/claude-hud/config.json. The README names colors.*, pathLevels, maxWidth, threshold overrides, display.timeFormat, display.hourCycle and display.promptCacheTtlSeconds as manual-only settings, and states that running the guided flow preserves them. The documented options include language (en, zh, zh-Hans, zh-Hant, zh-TW, default en), lineLayout (expanded or compact, default expanded), pathLevels (1 to 3, or full, default 1), maxWidth (number or null, default null), and forceMaxWidth (boolean, default false).

The maxWidth pair deserves attention. maxWidth is described as a fallback used only when terminal width detection fails completely, and forceMaxWidth makes it win even when detection returns a smaller value. That is a deliberate two-key design: one key covers detection failure, the other overrides detection. If your terminal reports a width that truncates the HUD, forceMaxWidth is the documented escape hatch.

There is also a layering rule for people who run several Claude config directories via CLAUDE_CONFIG_DIR and symlink plugins/ to a shared location. In that setup plugins/claude-hud/config.json is one physical file for all directories, so the README directs per-directory settings into $CLAUDE_CONFIG_DIR/claude-hud.json, which uses the same shape, needs only the keys it changes, and is layered on top of the shared config at load time. The README's example puts this in ~/.config/claude/work/claude-hud.json:

```json
{ "display": { "customLine": "Work Team" } }
```

Language handling has its own detail: English stays the default unless you opt in, zh maps to Simplified, zh-TW maps to Traditional, and the guided config writes the canonical zh-Hans or zh-Hant value.

## Where Claude HUD is the wrong tool

The plugin is a statusline, and a statusline is a few lines of text. It cannot show history, it cannot alert, and it cannot act. If you want a record of what happened across sessions, the transcript JSONL that the plugin reads is the better source, and the README does not present the HUD as a replacement for it.

The harder limitation is the dependency on Claude Code's own data. The plugin reads stdin JSON and the transcript; it does not instrument anything itself. That means the accuracy of the context bar, the tool list and the agent list is bounded by what Claude Code reports. The README is explicit that context data is native rather than estimated, which is a strength, but it also means a change in what Claude Code sends is a change in what the HUD can show.

Terminal rendering is the second constraint. The README ships maxWidth and forceMaxWidth precisely because width detection can fail or return a value that truncates the output. If you run the HUD in a narrow pane, expect to tune those keys rather than assume the layout adapts.

Finally, the install path assumes a working plugin marketplace and, on Windows, a JavaScript runtime. If your environment blocks the marketplace command or has no Node.js LTS, the HUD does not come up. The README gives no fallback install from a tarball or a manual clone, so there is no documented path around a blocked marketplace.

## Claude HUD compared with other terminal HUD projects

The related searches around this project include Codex HUD and Opencode HUD, which points at the real alternative category: statusline-style HUDs built for other coding agents. The difference is not cosmetic. Claude HUD is written against Claude Code's statusline API and reads Claude Code's stdin JSON and transcript JSONL. A HUD for another agent reads that agent's event stream instead. There is no shared interface to port between them, so the choice of HUD follows the choice of agent rather than the other way round.

Within Claude Code, the alternative is doing nothing and relying on the built-in statusline or on /compact discipline. The README's own framing is the counter-argument: "Know exactly how full your context window is before it's too late." If you already watch context manually and rarely run subagents, the HUD's agent and todo lines will sit unused, and Minimal mode exists for that case.

The other honest comparison is between the HUD and a logging or observability setup. A log gives you history and queryability; the HUD gives you a glance. The plugin's README does not claim to replace the transcript, and the transcript is what a postmortem would actually read.

## Maintenance, licence and upgrade cost

The repository is not archived. Its last push was on 2026-08-18, the same day as the v0.8.0 release, following v0.7.2 on 2026-08-17 and v0.7.1 on 2026-08-11. That is a recent cadence of small releases, and the changelog file in the repository root is the place to read what moved between them.

The licence is MIT, stated in package.json and in the LICENSE file. MIT is permissive, and the practical implication is that you can vendor or modify the plugin without a copyleft obligation; it is not legal advice, and if you redistribute a modified build you should read the licence text rather than this summary.

The upgrade cost sits in two places. First, the config file at ~/.claude/plugins/claude-hud/config.json holds manual settings that the guided flow preserves, so upgrades should not silently reset colors.* or the threshold overrides, but that is a behaviour to verify after each release rather than assume. Second, the plugin's build tooling is TypeScript compiled with tsc into dist/, and package.json declares engines.node >=18.0.0. If you build from source rather than installing through the marketplace, that is the floor. The repository ships a test script that builds and runs node --test, plus a test:stdin script that pipes a sample stdin JSON payload through dist/index.js, which is the fastest way to check a local build without a live session.

## Conclusion

Adopt Claude HUD if you already run Claude Code in a terminal and want context usage and tool activity visible without leaving the session; the install is three commands and the statusline API does the rendering. Skip it if you do not use Claude Code, or if you need a stable interface across CLI versions, because the plugin parses stdin JSON and transcript JSONL that Anthropic controls. Before committing, check that your Claude Code version has the statusline API, that a JavaScript runtime is present on Windows, and that the plugin loads in your terminal after /reload-plugins.

## FAQ

### How to install Claude HUD?

The README gives three steps inside a Claude Code instance: run /plugin marketplace add jarrodwatts/claude-hud, then /plugin install claude-hud, then /reload-plugins, and finally /claude-hud:setup to configure the statusline. The first two steps can also be run outside a session with the Claude Code CLI.

### What is Claude HUD?

It is a Claude Code plugin that renders a statusline below your input, showing context usage, active tools, running agents and todo progress. The README describes it as using Claude Code's native statusline API, with no separate window or tmux required.

### Is Claude HUD safe?

The repository is MIT licensed and the plugin runs as a statusline process invoked by Claude Code, reading stdin JSON and the session transcript. The README does not document any network calls or data collection, and the security policy lives in the repository's SECURITY.md file rather than in the README.

### How to use Claude HUD?

After install and setup, the HUD appears below your input and re-renders after each interaction, including new assistant messages, /compact and permission changes, debounced at 300ms. Run /claude-hud:configure to choose a preset, change the layout or language, and toggle individual elements.

## Sources

- [Official README](https://github.com/jarrodwatts/claude-hud#readme)
- [Project repository](https://github.com/jarrodwatts/claude-hud)
- [Release notes](https://github.com/jarrodwatts/claude-hud/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jarrodwatts-claude-hud