README.md

June 18, 2026 · View on GitHub

cc-hud preview — model, context bar, agents, rate limits, balance

CC-HUD

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

Model → Context → Agents → Rate Limits
_{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.

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

█▌

Context Bar
_{1/8-precision blocks
80-level granularity}

◧

Color
_{Catppuccin Mocha
dual-tone gradient}

◐

Agents
_{Running subagents
with type & model}

%

Rate Limits
_{5h / 7d usage
+ reset countdown}

0

Dependencies
_{Zero. Node.js
built-ins only}

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.

Via npm (manual)

npm i -g cc-hud

Add to ~/.claude/settings.json:

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

From source

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)

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}

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.).

Backend	`ANTHROPIC_BASE_URL`	Extra segment
DeepSeek	`https://api.deepseek.com/anthropic`	account balance — `¥13.44`
MiniMax	`https://api.minimaxi.com/anthropic`	Token Plan — `5h:17% (1.1h) │ 7d:2% (6.4d)`
GLM	`https://open.bigmodel.cn/api/anthropic` `https://api.z.ai/api/anthropic`	account balance — `¥88.50`

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