CC-HUD

A compact, single-line statusline plugin for Claude Code
_{Crash-free, zero-dependency status bar — model · thinking depth · context · agents · rate limits · top-model gauge}

Model · Depth  →  Context  →  Agents  →  Rate Limits  →  Top Model
_{everything you need, nothing you don't.}

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.

claude doctor                        # check which install you're on
npm i -g @anthropic-ai/claude-code   # switch to the npm build

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.

Upgrade

/plugin marketplace update cc-hud
/reload-plugins

npm i -g cc-hud

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

{
  "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 + thinking depth)
                              ↘ claude-refresh.js (detached → top-model weekly gauge, 5 min cache)

Thinking Depth & Top-Model Gauge

cc-hud shows your current thinking depth (the model's reasoning effort — Low / Medium / High / XHigh / Max) next to the model name, plus the top-tier-model weekly gauge — the "Current week (Opus / Fable)" meter from /usage that the statusline JSON doesn't expose:

[Fable 5 · XHigh] █▊░░░░░░░░ 18% │ 5h:1% (4.5h) │ 7d:35% (4.1d) │ Fable:51%

• Thinking depth is read straight from the session transcript (the latest turn's effort) — zero network, works on every backend. The badge hides itself when the transcript carries no effort.
• Top-model gauge comes from the same OAuth usage endpoint the /usage panel reads. The OAuth token is read locally (~/.claude/.credentials.json, or the macOS Keychain), used only for this read-only call, and never stored, logged, or refreshed.
• Fetches run in a detached background refresher — a statusline tick never waits on the network. Results are cached for 5 minutes.
• The gauge only activates on the official Anthropic backend with a subscription; API-key and third-party sessions skip it entirely.
• Opt out anytime: set CC_HUD_NO_REFRESH=1 to disable the background usage fetch (the transcript-read thinking depth is unaffected — it never touches the network).

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 (claude-fable-5 → Fable 5, 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           # 142 tests (node:test)

Project layout:

Star History

_{MIT License © Water}