best-claude-hud
Minimal Claude Code statusline HUD powered by Rust.
What is it?
What it is
A high-performance, minimal statusline HUD (Heads-Up Display) for Claude Code, written in Rust.
Why it exists
To provide essential real-time information during Claude Code sessions, including model and reasoning effort, workspace directory, Git status, context window usage, and optional usage/rate-limit metadata.
Who should use it
Claude Code usersTerminal usersDevelopers using CLI-based AI toolsLinux, macOS, and Windows terminal users
Who should avoid it
Users not using Claude CodeUsers who do not use a terminalUsers who prefer standard Claude Code statusline without extra metadata
How it works
A quick walkthrough in plain English
How best-claude-hud works
Step 1 of 3
You interact with it
Open best-claude-hud, send a request, or connect it to your stack.
Features
Advantages
- Lightweight and fast due to Rust implementation
- Seamless integration with Claude Code workflows
- Extensive customization options for appearance and data
- Open-source with permissive Apache-2.0 license
- Supports multiple operating systems and terminal setups
- Provides actionable insights (cost, context usage, Git status)
- Regular updates and active maintenance
- Community-driven development and contributions
Disadvantages
- Requires Claude Code and Git integration
- Initial setup may be complex for new users
- Some advanced features require manual configuration
- Nerd Font support needed for certain themes
- Limited to terminal environments
- Potential performance impact on low-resource systems
- Dependency on npm for installation
Installation
native
npm install -g best-claude-hud@latest && best-claude-hud --setup 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
FAQ
How do I install and configure best-claude-hud for the first time?
You can install it via npm using `npm install -g best-claude-hud@latest && best-claude-hud --setup`. The `--setup` command automatically configures your Claude Code `settings.json` file. Note that you must restart Claude Code after setup for changes to take effect.
Do I need to have Rust installed on my machine to use this tool?
No. The npm package includes prebuilt native binaries for MacOS, Linux, and Windows, so users do not need to have Rust installed to use the tool.
What information does the HUD display in the terminal?
The HUD provides a high-performance statusline showing the Claude model, live reasoning effort, workspace directory, Git branch and status (clean, dirty, or conflicts), context window usage, and optional segments like cost, usage, and rate limits.
Can I customize the appearance of the statusline?
Yes. You can use the `--config` command to open a TUI configuration interface or use `--theme <name>` to temporarily switch between built-in themes like 'nord', 'gruvbox', or 'tokyo-night'. Custom themes can be added to `~/.claude/best-claude-hud/themes/`.
How does the tool handle Git status without causing performance issues?
The HUD runs Git commands with the `--no-optional-locks` flag, which prevents the tool from creating unnecessary `.git/index.lock` contention while you are working.
Is there a way to use best-claude-hud without a global npm installation?
Yes, if you use the Nix package manager, you can run it without installing it globally using `nix run github:GaoSSR/best-claude-hud -- --help`.
Featured in Videos
YouTube tutorials and walkthroughs for best-claude-hud
Alternatives
Similar projects ranked by category, topics, and text overlap.
