best-claude-hud: A Rust statusline for Claude Code that respects your existing config

What the HUD actually shows and who needs it

best-claude-hud solves a narrow problem: Claude Code's default terminal output does not give you a persistent, glanceable status area. If you run long agentic sessions, you lose track of which model is active, how much context you have used, and whether your git working tree is clean. The tool reads Claude Code's statusLine data and renders it as a line at the bottom of the terminal. The README lists the default segments: model with live reasoning effort, the launch directory, git branch and dirty/conflict state, context window usage, and optional usage, rate-limit, cost, session, and output style segments. This is for developers who live in the terminal and want that information without switching panes. It is not for people who only run Claude Code occasionally and do not care about context limits.

How it gets its data: statusLine hook and fallback

Claude Code exposes a statusLine configuration option that lets an external command render a status line. best-claude-hud is that command. The README says the context window usage comes from Claude Code's official statusLine data, with an active-transcript fallback. That fallback matters because the official data may not always be present, especially in older versions or when the session state is incomplete. The model and reasoning effort come from the session transcript as well. The git segment is computed by the Rust binary itself, so it does not depend on Claude Code's own git integration. The directory segment is fixed at launch time, which the README notes is stable across temporary working-directory changes. That is a deliberate design choice: Claude Code often changes the working directory during a session, and the HUD shows where you started, not where the agent currently is.

Install and setup: one command, but read the caveats

Installation is straightforward. The npm package ships prebuilt native binaries, so you do not need Rust installed. The one-line setup is: npm install -g best-claude-hud@latest && best-claude-hud --setup. The --setup command writes a statusLine block into ~/.claude/settings.json and preserves existing settings. It resolves the installed command to an absolute path when possible, which avoids PATH issues. The README warns that existing sessions do not automatically reload settings.json, so you must restart Claude Code after setup. If you prefer manual configuration, you can add the statusLine block yourself, either with an absolute path or with a bare command name if your Claude Code sessions inherit the same PATH as your shell. The npm package intentionally does not install a binary into ~/.claude, so the global npm command is the only way it runs.

Nix integration: declarative, but it can clobber your settings

The project ships a Nix flake, which is a plus for reproducibility. You can run it without installing globally via nix run github:GaoSSR/best-claude-hud -- --help, or install it into a profile with nix profile install github:GaoSSR/best-claude-hud. The README gives a home-manager example that declaratively manages the entire ~/.claude/settings.json file. That example uses home.file.".claude/settings.json".text with a builtins.toJSON expression that sets the statusLine command to the Nix store binary. The README is explicit: this declaration 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. If you keep settings.json manually, run --setup instead. If Nix already manages the file, add statusLine to the existing Nix expression. The migration advice is concrete: copy every existing setting into Nix, then rename the original file as a backup before activation. This is the one place where the tool can actively hurt you if you ignore the warning.

Configuration files and themes: TOML under ~/.claude

All configuration lives under ~/.claude/best-claude-hud/. The main file is config.toml, which controls the HUD and segment layout. models.toml is created automatically on first run and controls model display names and context limits. Claude model families are recognized automatically, while third-party models can be customized with a pattern field, as shown in the truncated README example. Themes are TOML presets stored in themes/*.toml, and you can create custom themes in ~/.claude/best-claude-hud/themes/. You can temporarily override the configured theme with the --theme flag, and the README lists eight built-in themes including minimal, gruvbox, nord, and several powerline variants. The --config flag opens a TUI configuration interface, which is a nice touch for people who do not want to edit TOML by hand. The segment families are model, directory, git, context_window, usage, cost, session, output_style, and update. That is a lot of knobs, but the default line is minimal.

The --patch command: a separate tool inside the tool

One command stands out: best-claude-hud --patch <cli.js>. The README describes it as patching Claude Code's cli.js to address context warnings. This is not a statusline feature; it is a workaround for a Claude Code behavior that the project author found annoying. The command takes a path to cli.js, which is the main entry point of the Claude Code npm package. Patching a third-party package's source is fragile, because updates to Claude Code will overwrite the patch. The README does not explain what the patch changes or how to revert it. That is a limitation worth noting. If you rely on this patch, you need to reapply it after every Claude Code update, and you should verify that it does not break anything. The project does not document a --unpatch flag, so the safest path is to avoid this command unless you understand exactly what it does.

Limitations and where it is the wrong tool

The most obvious limitation is the Nix home.file example, which replaces the whole settings.json file. If you have other Claude Code settings that are not in Nix, you will lose them. The README warns about this, but it is easy to miss. A second limitation is that the HUD depends on Claude Code's statusLine hook. If Claude Code changes or removes that hook in a future version, the tool breaks. The active-transcript fallback mitigates missing statusLine data, but it is still a fallback, not a guarantee. Third, the tool is terminal-only. It does not integrate with editors like VS Code or JetBrains. If you use Claude Code through an IDE plugin, the HUD will not appear there. Fourth, the --patch command is fragile, as noted above. Finally, the tool is not for users who want a graphical dashboard or historical analytics. It is a single line of text, updated in real time, and nothing more.

Alternatives: what else does the same job

The main alternative is writing your own statusLine command, which is what Claude Code's hook is designed for. You can use a shell script or a small Python script that reads the same statusLine data and prints a line. The difference is that you would have to parse the data yourself, handle the fallback logic, and manage themes. best-claude-hud packages all of that into a single binary with a TUI configurator and a set of themes. Another alternative is to use Claude Code's built-in statusLine with a simple command like a git prompt, but that only gives you git status, not model or context info. The closest commercial alternative might be a terminal multiplexer plugin like tmux or zellij that can show session info, but those do not understand Claude Code's data format. The real difference is that best-claude-hud is purpose-built for Claude Code, whereas a generic statusline tool would need significant glue code to achieve the same result.

Maintenance and license

The project is licensed under Apache-2.0, which is permissive and allows commercial use with attribution. The repository is not archived, and the last push was on 2026-08-08, with releases v0.1.11, v0.1.10, and v0.1.9 in the preceding weeks. That suggests active maintenance, though the README does not document a change log or upgrade path. The npm update command is simply npm install -g best-claude-hud@latest, and the setup command will back up your settings.json if statusLine already exists. The update state is cached in .update_state.json, which suggests the tool checks for updates, but the README does not describe the update check behavior. The maintenance cost is low if you use the npm package, because the binary is prebuilt. The Nix flake requires updating the flake input to get new versions. The main upgrade risk is that a new version might change the config.toml schema, and the README does not mention any migration tooling. You should check the release notes before upgrading if you have a custom config.

Editorial conclusion

Adopt best-claude-hud if you want a fast, configurable statusline for Claude Code and you are comfortable with either running --setup or manually adding a statusLine block. Do not adopt it if you manage ~/.claude/settings.json by hand and refuse to back it up, because the Nix home.file example replaces the whole file. Before installing, verify that your Claude Code version supports the statusLine hook and that your terminal can render the theme you choose. Then run best-claude-hud --setup and restart Claude Code, since existing sessions do not reload settings.

Official sources

1. Official README
2. Project repository
3. Release notes