cc-hud

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, ~30ms 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:

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

Windows 用户： 原生安装器的 claude.exe 内嵌 Bun 运行时，正是 pas panic 崩溃的根源；npm 版跑在系统 Node.js 上，无此问题。用上面两条命令确认安装类型并切换。

[!NOTE] Also by WaterTian: SintBot. A self-hosted daemon that runs Claude Code (or Codex) headless on your own machine, so your team can hand it work from a Slack, Feishu or WeCom group. Each group gets its own project, model and permissions, and progress streams back to the chat. PolyForm Shield · npm i -g sintbot · sintbot.com

同作者项目：SintBot。 自托管的守护进程，在你自己的电脑上无头运行 Claude Code 或 Codex，团队在 Slack、飞书或企业微信群里给它派活；每个群各有项目、模型和权限，进度实时回到群里。PolyForm Shield · npm i -g sintbot · sintbot.com

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 (under $CLAUDE_CONFIG_DIR/bin/ when that variable is set) and points statusLine.command at it — quoted, forward slashes, so a Windows path or a home directory with a space survives the shell. 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      # opens the plugin panel and refreshes the marketplace — plugins installed from it are updated too
/reload-plugins                        # load the new version into the running session

[!NOTE] There is no /plugin update … slash command (an unknown word after /plugin just opens the panel). If the Installed tab still shows the old version, select cc-hud there and choose Update now, or run claude plugin update cc-hud@cc-hud in a terminal and restart Claude Code. Third-party marketplaces do not auto-update by default; turn it on in /plugin → Marketplaces → Enable auto-update (or extraKnownMarketplaces.cc-hud.autoUpdate: true in ~/.claude/settings.json) and Claude Code fetches new versions shortly after the first message of a session, then prompts Run /reload-plugins to apply.

[!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.

The package is published as cc-hud (@watertian/cc-hud is deprecated; if you installed it, npm rm -g @watertian/cc-hud and update the path below):

npm i -g cc-hud
npm root -g          # prints npm's global node_modules, e.g. /usr/local/lib/node_modules

Point statusLine.command at the installed entry by absolute path (the status-line shell may not have npm's global bin on PATH, so cc-hud / npx are not reliable there):

{
  "statusLine": {
    "type": "command",
    "command": "node \"/usr/local/lib/node_modules/cc-hud/dist/index.js\"",
    "padding": 2
  }
}

Upgrade with npm i -g cc-hud@latest; the path stays valid.

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
  }
}

/cc-hud:setup leaves a from-source command like this untouched (it only migrates version-pinned paths under ~/.claude/plugins/cache/) — the launcher resolves marketplace installs, not checkouts.

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 subagents)
                              ↘ git symbolic-ref / status (folder · branch*, 800ms budget)
                              ↘ refresh.js claude (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.1 · XHigh] █▊░░░░░░░░ 18% (1M) │ 5h:1% (4.5h) │ 7d:35% (4.1d) │ Fable:51% │ cc-hud · main* │ $0.42

• Thinking depth comes from the statusline stdin (effort.level), falling back to the session transcript on older Claude Code builds — zero network, works on every backend. The badge hides itself when neither carries an 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. If no refresh has succeeded for 30 minutes the gauge is shown as ~Fable:51% — "couldn't fetch" never looks like "fresh".

• 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 (thinking depth is unaffected — it never touches the network).

• Behind a proxy? Native fetch ignores HTTPS_PROXY, so once a proxy is configured (HTTPS_PROXY / https_proxy / ALL_PROXY, or the config file below) the request goes only through curl — native fetch is never tried, since it would leave the machine directly with your token. If curl fails, the refresh fails; it does not fall back to a direct connection. Without a proxy, native fetch is tried first and retried through curl on a transport failure or a WAF 403. Statusline processes often don't inherit your shell's proxy, so you can also put it in ~/.config/cc-hud/config.json (handed to curl as https_proxy):

  { "proxy": "http://127.0.0.1:7890" }
  

  A 401/404/500 is taken as the server's answer and not retried. CC_HUD_CURL=/path/to/curl picks a different curl binary (default: curl on PATH).

Workspace, spend cap & cost

• cc-hud · main* — current folder and git branch; * marks uncommitted tracked changes. Outside a repo (or on a detached HEAD) only the folder shows. Worktree sessions reuse the branch Claude Code already reports.
• spend:$12/$50 (3d) — the gateway spend limit (rate_limits.spend_limit), when your org sets one. Falls back to a bare percentage if the dollar figures aren't exposed.
• $0.42 — session cost estimate from Claude Code (cost.total_cost_usd); hidden while it is $0; set CC_HUD_NO_COST=1 to hide it always.
• —% in the context bar — Claude Code has not reported usage yet (start of session, or right after /compact until the next API call); it is not an empty context.
• Branch markers — * = uncommitted changes; ? = git status failed or exceeded its 800 ms budget (unknown, never shown as clean).
• Any other rate_limits window Claude Code adds later is listed as-is (one day:7%) rather than dropped.
• Subagents (up to three shown) are detected from the last 64 KB of the transcript. A very large tool result can push a still-running Agent call out of that window; if you want per-subagent rows regardless, Claude Code's own subagentStatusLine setting complements cc-hud.

Environment variables

Variable	Effect
CLAUDE_CONFIG_DIR	Claude Code's config directory (default ~/.claude). cc-hud reads .credentials.json and plugins/installed_plugins.json from it, and /cc-hud:setup puts the launcher in <dir>/bin/.
CC_HUD_NO_REFRESH=1	Never spawn the background usage refresher (no network at all on the official backend).
CC_HUD_NO_COST=1	Hide the session-cost segment.
CC_HUD_EXTRA_FILE=<path>	Show the file's first line as an extra segment (see Other backends).
CC_HUD_CURL=<path>	curl binary for proxied requests and the WAF fallback (default curl).
HTTPS_PROXY / https_proxy / ALL_PROXY / all_proxy	When set, usage requests go through curl only (native fetch ignores proxies and is skipped).
ANTHROPIC_BASE_URL	Read-only: decides the backend (official gauge vs DeepSeek / GLM / MiniMax detection by substring, see below).
ANTHROPIC_AUTH_TOKEN	Read-only: the API key used to query a third-party backend's balance / quota endpoint.

Boolean switches treat 0, false and an empty value as off.

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 with (1M) shown after the context bar, 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.

Details. Detection is by substring of ANTHROPIC_BASE_URL (deepseek, bigmodel.cn / api.z.ai, minimax — minimaxi.com selects the CN endpoint, anything else the global one). Results are cached in ~/.cache/cc-hud/ (ds-balance.json, glm-balance.json, mmx-quota.json; the official gauge uses claude-plan.json). On a cache miss these three collectors fetch inline with a 1.2 s budget, so a tick can take up to ~1.2 s once every 5 minutes; a hung endpoint only drops its own segment. When several extras apply, CC_HUD_EXTRA_FILE wins over DeepSeek, which wins over GLM.

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           # 227 tests (node:test; running the .ts tests needs Node ≥ 22.6 for type stripping — the shipped dist/ runs on ≥ 18)

Project layout:

Path	Purpose
src/	TypeScript source — entry, render, model normalize, transcript (agents + effort fallback), git workspace, shared cache + HTTP (proxy, curl fallback), Claude gauge / DeepSeek / MiniMax / GLM collectors, detached refresher
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

---