best-claude-hud

English | 简体中文 | 日本語

Minimal Claude Code statusline HUD, powered by Rust

best-claude-hud Overview

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.

The default statusline focuses on:

• Claude model display with live reasoning effort when available
• Claude Code launch directory, stable across temporary working-directory changes
• Git branch, clean/dirty/conflict state, and ahead/behind counts
• context window usage from Claude Code's official statusLine data, with active-transcript fallback
• optional usage/rate-limit, cost, session, and output style segments

Install

best-claude-hud is distributed through npm. The npm package uses prebuilt native binaries; users do not need Rust installed.

Install best-claude-hud and configure Claude Code in one line:

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

Restart Claude Code after setup. Existing sessions do not automatically reload ~/.claude/settings.json.

Install only:

npm install -g best-claude-hud@latest

Using yarn or pnpm:

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

For users in China:

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

Update an existing installation:

npm install -g best-claude-hud@latest

Uninstall:

npm uninstall -g best-claude-hud

Nix

best-claude-hud also ships a Nix flake for declarative and reproducible environments.

Run without installing globally:

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

Install into a Nix profile:

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

For home-manager or another declarative setup, point Claude Code directly at the Nix store binary. The example below declaratively manages the entire ~/.claude/settings.json file and does not merge existing settings. Use it only for a new file or when all Claude Code settings are declared in the same Nix configuration:

# In your flake inputs:
# best-claude-hud.url = "github:GaoSSR/best-claude-hud";

{ inputs, pkgs, ... }:

let
  hud = inputs.best-claude-hud.packages.${pkgs.system}.default;
in
{
  home.packages = [ hud ];

  home.file.".claude/settings.json".text = builtins.toJSON {
    statusLine = {
      type = "command";
      command = "${hud}/bin/best-claude-hud";
      padding = 0;
    };
  };
}

If you keep ~/.claude/settings.json manually, run best-claude-hud --setup or add the statusLine block directly; do not use this home.file declaration. If Nix already manages the file, add statusLine to the existing Nix expression. To migrate an unmanaged file to Home Manager, first copy every existing setting into Nix, then move the original file out of the way—for example, by renaming it as a backup—before activation.

Development shell:

nix develop

Claude Code Configuration

npm install -g best-claude-hud@latest only installs the command. Claude Code will not show the HUD until statusLine is configured.

Recommended:

best-claude-hud --setup

The setup command writes a statusLine block to ~/.claude/settings.json and preserves existing settings. It resolves the installed command to an absolute path when possible:

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

Manual configuration can also use "command": "best-claude-hud" if your Claude Code sessions inherit the same PATH as your shell. If statusLine already exists, --setup creates a timestamped backup next to settings.json before replacing it. Restart Claude Code after changing this file.

The npm package intentionally does not install a binary into ~/.claude. It uses the global npm command and resolves the matching native binary from Kiri-style npm alias optional dependencies.

Commands

best-claude-hud                    # open the interactive menu when run in a terminal
best-claude-hud --help             # print command help
best-claude-hud --version          # print version
best-claude-hud --setup            # configure Claude Code statusLine
best-claude-hud --config           # open the TUI configuration interface
best-claude-hud --theme minimal    # temporarily render with a built-in theme
best-claude-hud --patch <cli.js>   # patch Claude Code cli.js context warnings

Themes

Temporarily override the configured theme:

best-claude-hud --theme cometix
best-claude-hud --theme minimal
best-claude-hud --theme gruvbox
best-claude-hud --theme nord
best-claude-hud --theme powerline-dark
best-claude-hud --theme powerline-light
best-claude-hud --theme powerline-rose-pine
best-claude-hud --theme powerline-tokyo-night

Custom themes can be stored under:

~/.claude/best-claude-hud/themes/

Then use:

best-claude-hud --theme my-custom-theme

Configuration

Configuration files are stored under:

~/.claude/best-claude-hud/

Important files:

• config.toml: main HUD and segment configuration
• models.toml: model display names and context window limits
• themes/*.toml: custom theme presets
• .api_usage_cache.json: optional usage API cache
• .update_state.json: update-check state

Run the TUI configurator:

best-claude-hud --config

Available segment families:

• model
• directory
• git
• context_window
• usage
• cost
• session
• output_style
• update

Model Configuration

models.toml is created automatically on first run:

~/.claude/best-claude-hud/models.toml

It controls model display names and context limits. Claude model families are recognized automatically, while third-party models can be customized:

[[models]]
pattern = "kimi-k2.7"
display_name = "Kimi K2.7"
context_limit = 262144

[[models]]
pattern = "glm-5"
display_name = "GLM-5"
context_limit = 200000

[[models]]
pattern = "qwen3-coder"
display_name = "Qwen Coder"
context_limit = 256000

[[context_modifiers]]
pattern = "[1m]"
display_suffix = " 1M"
context_limit = 1000000

Statusline Data

Claude Code sends statusLine data to the command through stdin. best-claude-hud reads:

• model
• effort.level, shown as a separate item when the current model supports reasoning effort
• workspace.project_dir for the stable Claude Code launch directory
• workspace.current_dir as a fallback for older Claude Code versions
• transcript_path
• session_id, used to scope Ultracode detection to the current Claude Code process
• context_window
• cost
• output_style
• rate_limits

The effort item follows the model name with an explicit ASCII pipe and a brain icon, for example Kimi K2.7 | 🧠 max. Its label is rendered in bright purple (#B45CFF). The HUD displays low, medium, high, xhigh, max, or ultracode; Nerd Font and Powerline modes use the matching Nerd Font brain glyph.

Claude Code's official statusline payload reports Ultracode as xhigh. To keep ordinary xhigh and Ultracode distinct, the HUD cross-checks successful /effort events from the current Claude Code process only. Events from an earlier process are ignored when a conversation is resumed. An xhigh CLAUDE_CODE_EFFORT_LEVEL override remains compatible with Ultracode, while other active overrides prevent it from being reported. If Claude Code does not provide effort data, unsupported and third-party models keep the existing model-only display. The Claude Code version field is intentionally not shown.

For context window usage, the HUD prefers Claude Code's official context_window fields. The active transcript is used only as a compatibility fallback when those fields are absent, null, or temporarily zero. All-zero usage placeholders written after an interrupted response are ignored, so pressing Esc does not erase the last valid context reading. A genuinely new session with no usage still shows 0% · 0 tokens and never scans older project history.

Git Status Indicators

• ✓: clean working tree
• ●: dirty working tree
• ⚠: conflicts
• ↑n: commits ahead of upstream
• ↓n: commits behind upstream

Git commands run with --no-optional-locks, so the HUD does not create unnecessary .git/index.lock contention while you work.

Claude Code Patch Utility

The inherited patcher can patch Claude Code cli.js to reduce context warning noise:

best-claude-hud --patch /path/to/claude-code/cli.js

Example:

best-claude-hud --patch ~/.local/share/fnm/node-versions/v24.4.1/installation/lib/node_modules/@anthropic-ai/claude-code/cli.js

The patcher creates a backup next to the target file before writing.

Platform Support

Requirements

• Claude Code with statusLine support
• Git for branch/status display
• A terminal with ANSI color support
• A Nerd Font if you choose Nerd Font or Powerline themes

Development

For maintainers and contributors working from source:

cargo fmt
cargo clippy -- -D warnings
cargo test
cargo build --release
cargo run -- --help
npm --prefix packaging/npm run check
npm --prefix packaging/npm run test

Release

Maintainers must follow the complete, approval-gated checklist in RELEASING.md. It is the source of truth for version updates, local verification, Git tags, GitHub Releases, npm publishing, and local installation upgrades.

Project Resources

• Changelog
• Contributing guide
• Release process
• Security policy
• Upstream triage

Acknowledgements

Third-party attribution is preserved in NOTICE.

License

Licensed under the Apache License 2.0.