# best-claude-hud: a Rust statusline HUD for Claude Code

> best-claude-hud replaces the default Claude Code statusline with a Rust binary that renders model, reasoning effort, Git state and context usage. It is small, configurable through a TUI, and distributed as prebuilt npm binaries, but the setup path has sharp edges around settings.json and Nix.

**GaoSSR/best-claude-hud** — Minimal Claude Code statusline HUD powered by Rust. Use it only for a new file or when all Claude Code settings are declared in the same Nix configuration: 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.

- Repository: https://github.com/GaoSSR/best-claude-hud
- Stars: 1,119 · Forks: 23
- Language: Rust
- License: Apache-2.0
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/gaossr-best-claude-hud

## The statusline problem best-claude-hud targets

Claude Code lets you put a command behind the statusline, and the default one tells you very little. You get a working directory and not much else. The questions that actually slow a session down are different: how much of the context window is left, whether the branch is ahead or behind, what model is answering, and whether reasoning effort is currently raised. best-claude-hud is a Rust binary that answers those in one row.

The audience is narrow and specific. It is for people who run Claude Code in a terminal all day and read the statusline reflexively. It is not a dashboard, not a session manager, and not a wrapper around the CLI. The README describes it as a "high-performance Claude Code statusline tool written in Rust", and the scope stays inside that sentence. If you want a graphical view of token spend across projects, this is the wrong shape of tool.

## What the HUD actually renders

The default statusline is built from segment families: model, directory, git, context_window, usage, cost, session, output_style and update. Each can be configured. The model segment shows the Claude model and, when the data is available, live reasoning effort. The directory segment shows the Claude Code launch directory, which the README says stays stable across temporary working-directory changes, so a subshell cd does not rewrite your statusline. The git segment reports branch, clean or dirty or conflict state, and ahead/behind counts.

Context window usage is the interesting one. It comes from Claude Code's official statusLine data, with a fallback to the active transcript when that data is not present. That fallback matters because it means the segment can still produce a number on versions or paths where the official field is missing, though the README does not describe how the two sources are reconciled when they disagree.

Usage and rate-limit metadata is optional, and the README calls it optional for a reason. It depends on an API cache file, .api_usage_cache.json, rather than being free local data. Cost, session and output_style are likewise opt-in segments. The update segment exists to check for new versions, with state kept in .update_state.json.

## Installing best-claude-hud and configuring Claude Code

The npm package ships prebuilt native binaries, so Rust is not required on the machine. The README gives a one-line install plus setup:

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

After that, restart Claude Code. The README states plainly that existing sessions do not automatically reload ~/.claude/settings.json, so a running session keeps the old statusline until you restart it.

Installing alone does nothing visible. The README is explicit that npm install only installs the command and that Claude Code will not show the HUD until statusLine is configured. The setup command writes this block into ~/.claude/settings.json while preserving existing settings:

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

It resolves the installed command to an absolute path when possible. Manual configuration can use "command": "best-claude-hud" instead, but only 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.

Once it is running, the TUI configurator is where most tuning happens:

```bash
best-claude-hud --config
```

Configuration lives under ~/.claude/best-claude-hud/, with config.toml for the HUD and segments, models.toml for display names and context limits, and themes/*.toml for custom presets. models.toml is created automatically on first run. Third-party models can be added with a pattern entry:

```toml
[[models]]
pattern = "kimi-
```

The README truncates that example, so the exact matching semantics for a custom pattern are not fully documented. Treat the pattern field as something to test rather than assume. Themes can be previewed without committing to them:

```bash
best-claude-hud --theme gruvbox
```

Built-in themes include minimal, cometix, gruvbox, nord, powerline-dark, powerline-light, powerline-rose-pine and powerline-tokyo-night. Users in China get a registry mirror variant of the install command, and yarn and pnpm global installs are documented as alternatives.

## The Nix path is powerful and easy to misuse

best-claude-hud ships a flake, and the README is unusually blunt about the risk. The home-manager example declares the entire ~/.claude/settings.json file and does not merge existing settings. The README repeats the warning twice: use it only for a new file or when all Claude Code settings are declared in the same Nix configuration.

That is a real failure mode. If you have hand-edited settings.json with permissions, hooks or environment entries and you drop in the home.file declaration, activation overwrites the file with a JSON object containing only statusLine. The README tells you what to do instead: run best-claude-hud --setup, or add the statusLine block directly. To migrate an unmanaged file to Home Manager, copy every existing setting into Nix first, then move the original file out of the way (the README suggests renaming it as a backup) before activation. If Nix already manages the file, add statusLine to the existing expression rather than creating a second one.

For a quick look without installing anything globally, the flake supports a direct run:

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

A development shell is available with nix develop. The flake is a genuine convenience for declarative setups, but the all-or-nothing settings.json declaration is the sharpest edge in the whole project.

## Where best-claude-hud is the wrong tool

The npm package intentionally does not install a binary into ~/.claude. It relies on the global npm command and resolves the matching native binary from npm alias optional dependencies. That design keeps the package small, but it means the statusline command depends on the npm global prefix being present and on PATH being identical between your shell and the Claude Code process. If Claude Code is launched from a desktop entry, a systemd unit or an editor that does not source your shell profile, the absolute path that --setup writes is doing real work, and a manual "command": "best-claude-hud" is likely to fail silently with an empty statusline.

The usage and rate-limit segments are a second boundary. They are optional and depend on an API cache, so anyone expecting accurate spend numbers purely from local transcript data will be disappointed; the README frames usage and rate-limit metadata as optional rather than guaranteed. The cost and session segments are similarly opt-in.

Finally, the project is a statusline, not an observability system. There is no history, no aggregation across sessions, no export. If you need to answer "how many tokens did this team burn last week", a statusline renderer is the wrong layer. The README also documents a --patch <cli.js> command for patching Claude Code context warnings, which reaches into Claude Code's own installation; that is a maintenance liability whenever Claude Code updates, and the README does not describe how the patch survives an upgrade.

## How it compares to wiring your own statusline script

The obvious alternative is a shell script or a small Python program that reads the JSON Claude Code passes to the statusline command and prints a formatted line. That approach has real advantages: no global npm install, no native binary resolution, no dependency on the npm prefix, and full control over output. A shell script also survives a Claude Code upgrade untouched.

The trade-off is everything the README lists as segments. Git ahead/behind counts, conflict detection, context window fallback to the active transcript, model display names with context limits in models.toml, and a TUI configurator are all work you would otherwise write and maintain yourself. The Rust binary also renders with unicode-width awareness and ships eight built-in themes, which a quick shell one-liner will not match.

A second alternative is simply keeping Claude Code's default statusline. That costs nothing and breaks nothing. best-claude-hud is worth the install only if you actually look at context usage or Git state during a session. If you never act on those numbers, the default is the correct choice.

## Maintenance, licence and upgrade cost

The repository is not archived and the last push was on 2026-08-08, the same date as the v0.1.11 release. Releases are frequent and close together: v0.1.9 on 2026-07-22, v0.1.10 on 2026-07-23, v0.1.11 on 2026-08-08. That cadence suggests the project is moving, and it also means the update segment and the .update_state.json file have something to report fairly often.

Upgrading is the same command as installing:

```bash
npm install -g best-claude-hud@latest
```

Because the npm package resolves a native binary per platform, an upgrade pulls a new binary rather than rebuilding one. The release profile in Cargo.toml uses opt-level = "z", strip = true, lto = true, codegen-units = 1 and panic = "abort", which points at binary size as a deliberate goal. That is a reasonable choice for a statusline that runs on every prompt render, though panic = "abort" means a crash produces no unwinding and no backtrace, which makes field debugging harder.

The licence is Apache-2.0, declared in both Cargo.toml and the LICENSE file, with a NOTICE file present. Apache-2.0 includes an explicit patent grant and requires that NOTICE contents be preserved in redistributions. If you vendor the binary or repackage it internally, keep the NOTICE file with it. This is a description of the licence text, not legal advice; check with your own counsel for anything beyond personal use.

## Conclusion

Adopt best-claude-hud if you already live in a Claude Code terminal session and want context window usage, Git ahead/behind counts and reasoning effort visible without leaving the prompt. Skip it if you rely on a hand-edited ~/.claude/settings.json that you are not willing to back up, or if you want a GUI dashboard rather than a single statusline row. Before installing, verify that your Claude Code version writes statusLine data and that the global npm prefix is on the PATH your Claude Code sessions inherit; then run best-claude-hud --setup and restart the session.

## FAQ

### How do I install and set up best-claude-hud?

Install it globally from npm and run the setup command in one line: npm install -g best-claude-hud@latest && best-claude-hud --setup. The npm package ships prebuilt native binaries, so Rust is not required. Restart Claude Code afterwards, because existing sessions do not automatically reload ~/.claude/settings.json.

### Does best-claude-hud replace the default Claude Code statusline?

It configures Claude Code's statusLine setting to run the best-claude-hud command, so the HUD is what renders in that row. Installing the npm package alone changes nothing until statusLine is configured, either by best-claude-hud --setup or by adding the block manually.

### Can I use best-claude-hud without installing Rust?

Yes. The README states the npm package uses prebuilt native binaries and that users do not need Rust installed. A Nix flake is also available if you prefer a declarative install.

### Where does best-claude-hud store its configuration?

Configuration files live under ~/.claude/best-claude-hud/. The main files are config.toml for the HUD and segment configuration, models.toml for model display names and context window limits, and themes/*.toml for custom theme presets.

## Sources

- [Official README](https://github.com/GaoSSR/best-claude-hud#readme)
- [Project repository](https://github.com/GaoSSR/best-claude-hud)
- [Release notes](https://github.com/GaoSSR/best-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/gaossr-best-claude-hud