Skip to content
Get packs

Guide · Open source

How to use claude-hud: install and configure the Claude Code status line

Updated · written with AI from the project's own documentation and checked against our catalogue data

Claude HUD is an open-source plugin for Claude Code, Anthropic's coding assistant. It adds a status display below your input box that shows context usage, subscriber rate limits, the current model, project path and git branch. This guide covers installing it, reading the display, turning on optional lines and changing the settings.

Claude HUDjarrodwatts/claude-hud · ★ 29.1k · MIT

Quick start

  1. 1Check prerequisites. Make sure Claude Code is installed. On Windows, install Node.js LTS if you have not already.
  2. 2Add the marketplace. Inside Claude Code, run /plugin marketplace add jarrodwatts/claude-hud.
  3. 3Install the plugin. Run /plugin install claude-hud, then /reload-plugins.
  4. 4Run setup. Run /claude-hud:setup to point your status line at the HUD.
  5. 5Turn on optional lines. Run /claude-hud:configure to add tools, agents or todo lines and adjust the layout.
  6. 6Update when needed. Enable auto-update in /plugin, or run the update commands from the terminal and then /reload-plugins.

What you need before you install claude-hud

You need Claude Code. The plugin only works inside Claude Code, so it is no use if you do not use that tool.

On Windows, you also need Node.js LTS. The setup step needs a JavaScript runtime, and the README says to install Node.js if setup reports that none was found.

  • Claude Code
  • Node.js LTS (required on Windows if setup reports no JavaScript runtime)

Install claude-hud inside Claude Code

Open Claude Code and run the four commands below in order. The first adds the plugin marketplace, the second installs the plugin, the third reloads plugins, and the fourth points your status line at the HUD.

The README notes that Claude Code reloads settings on its own, so the HUD should appear right away after setup.

  • The README also gives a terminal route: claude plugin marketplace add jarrodwatts/claude-hud, then claude plugin install claude-hud@claude-hud, then run /reload-plugins and /claude-hud:setup inside a session.
/plugin marketplace add jarrodwatts/claude-hud /plugin install claude-hud /reload-plugins /claude-hud:setup

Fix the Windows error: no JavaScript runtime found

If setup says no JavaScript runtime was found on Windows, install Node.js LTS, restart your shell, and run setup again. The README gives a winget command for this.

  • Restart your shell after installing Node.js.
  • Run /claude-hud:setup again.
winget install OpenJS.NodeJS.LTS

Read the default display

The default layout is two lines. Line 1 shows the model, a provider label when one is detected (Bedrock, Vertex or MiniMax), the project path and the git branch. Line 2 shows how full the context window is and your subscriber rate limits.

The context bar changes colour from green to yellow to red as it fills. The usage bar shows when the rate limit resets.

  • Line 1: model, provider label if detected, project path, git branch
  • Line 2: context used and subscriber rate limits
[Opus] │ my-project git:(main*) Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (resets in 1h 30m)

Turn on tools, agents and todo lines

Optional lines show which tools are running, which agents are active and your todo progress. You turn these on with /claude-hud:configure. The README says the tools, agents and todos lines also read the session transcript.

  • Tools: which tools are running and how many times
  • Agents: which agents are active and how long they have run
  • Todos: progress through your task list
/claude-hud:configure

Change settings in the config file

The guided /claude-hud:configure flow covers layout, activity lines, session info, usage, git, language and a custom line. It previews changes before saving and keeps settings it does not ask about.

Other settings live in ~/.claude/plugins/claude-hud/config.json, or under $CLAUDE_CONFIG_DIR if you set that. Invalid values fall back to their defaults. Useful options include lineLayout (expanded or compact), pathLevels (1 to 3 or full), and gitStatus settings such as showDirty and showAheadBehind.

  • lineLayout: expanded (multi-line) or compact (single line); default expanded
  • pathLevels: 1 to 3, or full; default 1
  • gitStatus.showDirty: shows * for uncommitted changes; default true
  • display.showProvider: shows the provider label before the model; default false
~/.claude/plugins/claude-hud/config.json

Keep claude-hud up to date

Claude Code does not auto-update third-party plugins by default. To turn auto-update on, run /plugin, open Marketplaces, select claude-hud, and choose Enable auto-update. If that option is missing or updates do not arrive, update by hand from the terminal.

After a manual update, run /reload-plugins in any open session. You do not need to run setup again.

claude plugin marketplace update claude-hud claude plugin update claude-hud@claude-hud

What people use it for

  • Watch context usage while you work in a long Claude Code session.
  • Track subscriber rate limits and their reset time while coding.
  • Follow running agents and todo progress during long multi-step tasks.
  • Show the git branch and uncommitted-changes marker in the status line.
  • Use a compact single-line layout or a custom label for a shared config directory.

Frequently asked questions

Is claude-hud free?

claude-hud is released under the MIT licence, which the project lists on its repository. The README does not list any price, so check the repository for current licence terms.

What do I need to run claude-hud?

You need Claude Code. On Windows you also need Node.js LTS, which the setup step needs when it reports that no JavaScript runtime was found.

Why does claude-hud say no JavaScript runtime was found?

This happens on Windows when Node.js is not installed. Install Node.js LTS with winget install OpenJS.NodeJS.LTS, restart your shell, and run /claude-hud:setup again.

Why isn't claude-hud updating automatically?

Claude Code does not auto-update third-party plugins by default. You can turn on Enable auto-update in /plugin under Marketplaces, or update by hand with the claude plugin update commands and then run /reload-plugins.

Does claude-hud open a separate window?

No. It runs as a status line command inside Claude Code, so it needs no separate window or tmux and works in any terminal, according to the README.

Can I show the HUD in a different language or layout?

Yes. Labels are available in English, Simplified Chinese and Traditional Chinese. You can set lineLayout to compact for a single line, and change the language through /claude-hud:configure or the config file.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Claude HUD suits developers who use Claude Code every day and want context usage, rate limits or agent progress visible without extra software. It is not useful if you do not use Claude Code, and you should expect to update it by hand unless you turn on auto-update.

Install options & downloads