KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #developer-tools #claude-code #ai-agent #codex #deepseek-harness #ai-agents #cli #react #mcp

best-claude-hud

★ 243 Open GitHub ↗

Minimal Claude Code statusline HUD powered by Rust.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h4 align="right"><strong><a href="./README.md">English</a></strong> | <a href="./README_CN.md">简体中文</a> | <a href="./README_JA.md">日本語</a></h4>

<h3 align="center"><nobr>Minimal Claude Code statusline HUD, powered by Rust</nobr></h3>

---

## 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:

```bash
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:

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

Using yarn or pnpm:

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

For users in China:

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

Update an existing installation:

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

Uninstall:

```bash
npm uninstall -g best-claude-hud
```

## Nix

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

Run without installing globally:

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

Install into a Nix profile:

```bash
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:

```nix
# 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:

```bash
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:

```bash
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:

```json
{
  "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

```bash
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:

```bash
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:

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

Then use:

```bash
best-claude-hud --theme my-custom-theme
```

## Configuration

Configuration files are stored under:

```text
~/.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:

```bash
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:

```text
~/.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:

```toml
[[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:

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

Example:

```bash
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

| Platform | Native binary source | Status |
| --- | --- | --- |
| MacOS arm64 | Native binary selected automatically by npm | Supported |
| MacOS x64 | Native binary selected automatically by npm | Supported |
| Linux x64 musl | Native binary selected automatically by npm | Supported |
| Windows x64 | Native binary selected automatically by npm | Supported |
| Linux arm64 / Windows arm64 | - | Planned |

## 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:

```bash
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](./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](./CHANGELOG.md)
- [Contributing guide](./CONTRIBUTING.md)
- [Release process](./RELEASING.md)
- [Security policy](./SECURITY.md)
- [Upstream triage](./docs/triage.md)

## Acknowledgements

Third-party attribution is preserved in [NOTICE](./NOTICE).

## License

Licensed under the [Apache License 2.0](./LICENSE).

best-claude-hud

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README