best-claude-hud

What it is

best-claude-hud is a high-performance Claude Code statusline tool written in Rust. It shows the status information you actually need while using Claude Code in a terminal: model and live reasoning effort, workspace, Git branch/status, context window usage, and optional usage/rate-limit metadata.

How it works

The tool reads statusLine data from Claude Code via stdin, including fields such as model, effort.level, workspace, transcript_path, session_id, context_window, cost, and rate_limits. It renders a statusline with model display, live reasoning effort when available, and various segments. It supports multiple themes and can be configured via a statusLine block in ~/.claude/settings.json or via the interactive UI. It can patch Claude Code CLI warnings and offers a patch utility to adjust context warning noise.

Getting started

Install via npm (prebuilt binaries are used; Rust is not required for users):

npm install -g best-claude-hud@latest && best-claude-hud --setup

Or install only:

npm install -g best-claude-hud@latest

If using yarn or pnpm:

yarn global add best-claude-hud@latest
pnpm add -g best-claude-hud@latest

For China users:

npm install -g best-claude-hud@latest --registry https://registry.npmmirror.com && best-claude-hud --setup

To update:

npm install -g best-claude-hud@latest

Uninstall:

npm uninstall -g best-claude-hud

Nix users can run or install via flakes:

nix run github:GaoSSR/best-claude-hud -- --help

nix profile install github:GaoSSR/best-claude-hud
best-claude-hud --setup

Configure Claude Code by running setup to write a statusLine block into ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "/path/to/best-claude-hud",
    "padding": 0
  }
}

Manual configuration can also use "command": "best-claude-hud". If a statusLine already exists, --setup creates a timestamped backup next to settings.json before replacing it.

Recent releases

The latest five releases show a consistent npm-first installation emphasis:

• v0.1.10 (2026-07-23): Highlights include npm-first installation with platform-specific native binaries.
• v0.1.9 (2026-07-22): Highlights include npm-first installation with platform-specific native binaries.
• v0.1.8 (2026-07-22): Highlights include npm-first installation with platform-specific native binaries.
• v0.1.7 (2026-07-18): Highlights include npm-first installation with platform-specific native binaries.
• v0.1.6 (2026-07-17): Highlights include npm-first installation with platform-specific native binaries.

Traction

GitHub stars: 1073

Behind the repo

Not provided in the README excerpt.

Caveats

• License: Apache-2.0.
• Requires Claude Code with statusLine support, Git for branch/status, and a terminal with ANSI color support.
• The npm package uses prebuilt native binaries; Rust is not required for end users.