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.
 
 
 
 
= 18" />
 
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:** the native installer's claude.exe embeds a Bun runtime — the very source of the pas panic crash. The npm build runs on your system Node.js and doesn't have the problem:
>
>
>
> **Windows 用户：** 原生安装器的 claude.exe 内嵌 Bun 运行时，正是 pas panic 崩溃的根源；npm 版跑在系统 Node.js 上，无此问题。用上面两条命令确认安装类型并切换。
Features
█▌ Context Bar 1/8-precision blocks 80-level granularity
★ Depth & Top Model Thinking-depth badge Opus/Fable weekly gauge
◐ Agents Running subagents with type & model
% Rate Limits 5h / 7d usage + reset countdown
◧ Color Catppuccin Mocha dual-tone gradient
0 Dependencies Zero. Node.js built-ins only
Install
Inside Claude Code:
**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
> [!NOTE]
> The launcher resolves the currently installed cc-hud version on each tick, so upgrades need **no re-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.
Via npm (manual)
Add to ~/.claude/settings.json:
From source
Add to ~/.claude/settings.json:
How It Works
Stateless Fresh process per tick zero memory leaks
Fast ~60ms render within 300ms debounce
Safe 2s hard timeout all IO try-catch
Upgrade-safe Stable launcher (v0.5+) no re-setup on upgrade
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:
- **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.