Why CC-HUD?

Problem. Claude Code's native installer bundles Bun, which has a known memory allocator bug on Windows (oven-sh/bun#25082). Statusline plugins like jarrodwatts/claude-hud run on every tick, amplifying memory pressure and making pas panic crashes far more likely.

Solution. CC-HUD is a crash-free alternative — pure Node.js, zero deps, stateless per call, ~60ms render, 2s hard timeout. Designed to keep your status bar running without taking Claude Code down.

[!TIP] Windows users: Use npm i -g @anthropic-ai/claude-code instead of the native installer to avoid Bun crashes entirely.

Windows 用户： 建议用 npm i -g @anthropic-ai/claude-code 代替原生安装器，彻底规避 Bun 崩溃。

Features

Install

Inside Claude Code:

/plugin marketplace add WaterTian/cc-hud
/plugin install cc-hud@cc-hud
/reload-plugins
/cc-hud:setup        # idempotent; safe to re-run

Done — no restart needed; /reload-plugins hot-loads the HUD.

[!NOTE] /cc-hud:setup installs a tiny launcher at ~/.claude/bin/cc-hud-launcher.cjs and points statusLine.command at it. It is idempotent — re-running migrates old version-pinned paths and skips when already current. If statusLine is managed by cc-bot's shim, setup detects this and leaves it alone (the shim already wraps cc-hud transparently).

Upgrade

/plugin marketplace update cc-hud
/reload-plugins

[!NOTE] Since v0.5.0, /cc-hud:setup installs a small launcher at ~/.claude/bin/cc-hud-launcher.cjs and points statusLine.command at it. The launcher resolves the currently installed cc-hud version on each tick, so plugin upgrades no longer require re-running /cc-hud:setup.

Upgrading from ≤0.4.x? Re-run /cc-hud:setup once — it auto-detects the old version-pinned path and migrates it to the launcher.

npm i -g cc-hud

Add to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "npx cc-hud",
    "padding": 2
  }
}

git clone https://github.com/WaterTian/cc-hud.git
cd cc-hud && npm install && npm run build

Add to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "node /absolute/path/to/cc-hud/dist/index.js",
    "padding": 2
  }
}

How It Works

Claude Code ──stdin JSON──→  ~/.claude/bin/cc-hud-launcher.cjs   ← stable path (v0.5+)
                              │ resolves the currently installed cc-hud
                              ▼
                             cc-hud dist/index.js  ──stdout──→ status bar
                              ↘ transcript JSONL (tail 64KB → active agents)

Auto-detected Backends

cc-hud detects your ANTHROPIC_BASE_URL and pulls balance / quota automatically — zero configuration, cached locally for 5 minutes. Model names are beautified along the way (glm-5.2[1m] → GLM 5.2 (1M), MiniMax-M3 → MiniMax M3, etc.).

Example output:

[DeepSeek V4 Pro] ██░░░░░░░░ 20% │ ¥13.44
[MiniMax M3]      █▎░░░░░░░░ 13% │ 5h:17% (1.1h) │ 7d:2% (6.4d)
[GLM 5.2]         ████▏░░░░░ 41% (1M) │ ¥88.50

Works with dscode / mmcode / glmcode / ZCode or any launcher that exports ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN.

Other backends

Set the CC_HUD_EXTRA_FILE env var to any file whose first line is the text to display. See scripts/ds-balance-cache.sh for a reference cache implementation.

Development

npm install
npm run build      # compile TypeScript → dist/
npm test           # 95 tests (node:test)

Project layout:

| Path | Purpose | | --- | --- | | src/ | TypeScript source — entry, render, model normalize, DeepSeek / MiniMax / GLM pickers | | scripts/launcher.cjs | Stable-path launcher (/cc-hud:setup copies it to ~/.claude/bin/) | | commands/setup.md | /cc-hud:setup slash command | | tests/ | node:test unit tests (TS + CJS) | | dist/ | Compiled output, committed |

Star History