cc-hud — agent reference

Compact single-line status bar for Claude Code, plus a one-command native footer preset for Codex CLI. This file is the machine-oriented reference: exact commands with expected output, the runtime contract, every file, process and endpoint the tool touches, and the invariants to keep when changing it. The human tour is README.md; maintainer notes (Chinese) are in CLAUDE.md. Keep the three in sync when behaviour changes.

What it renders

[Fable 5.1 · XHigh] █▊░░░░░░░░ 18% (1M) │ ◐ explore [haiku] │ 5h:1% (4.5h) │ 7d:35% (4.1d) │ Fable:51% │ spend:$12/$50 (3d) │ cc-hud · main*

Colors: Catppuccin Mocha, ANSI 256. Percent colour steps at 50 / 70 / 85.

Install for a user (inside Claude Code)

/plugin marketplace add WaterTian/cc-hud
/plugin install cc-hud@cc-hud
/reload-plugins
/cc-hud:setup

/cc-hud:setup is itself an agent-executed procedure (commands/setup.md): it copies scripts/launcher.cjs to <cfg>/bin/cc-hud-launcher.cjs and sets statusLine.command to node "<cfg>/bin/cc-hud-launcher.cjs" in <cfg>/settings.json (cfg = $CLAUDE_CONFIG_DIR or ~/.claude). It is idempotent and merges into existing settings. The launcher resolves the newest marketplace-installed cc-hud on every tick, so upgrades never need a re-setup.

Verify (works in any shell; <cfg> expanded, refresh spawning disabled):

echo '{"model":{"id":"claude-fable-5-1"},"context_window":{"used_percentage":13}}' \
  | CC_HUD_NO_REFRESH=1 node "<cfg>/bin/cc-hud-launcher.cjs" | sed 's/\x1b\[[0-9;]*m//g'

Upgrade: /plugin marketplace update cc-hud then /reload-plugins. There is no /plugin update slash command; from a terminal use claude plugin update cc-hud@cc-hud.

Uninstall: remove the statusLine key from <cfg>/settings.json, delete <cfg>/bin/cc-hud-launcher.cjs, run claude plugin uninstall cc-hud@cc-hud, and optionally rm -rf ~/.cache/cc-hud.

Without the marketplace: npm i -g cc-hud (or a source checkout + npm run build) and point statusLine.command at node "<absolute path>/dist/index.js"; /cc-hud:setup leaves such a command untouched.

Codex CLI is a different install path and config file — see Codex native footer below.

Runtime contract

The stdin contract below applies to dist/index.js (Claude) and to the npm entry dist/cli.js with no arguments. Explicit CLI commands have ordinary command output and nonzero exit codes on failure.

• Input: Claude Code's statusline JSON on stdin (schema). Fields read are typed in src/types.ts (StdinData); everything else is ignored. Empty, malformed or non-object stdin renders the bare [Claude] line.
• Output: exactly one line on stdout, ANSI-256 coloured, then exit 0 — always, including on internal errors (the fallback line) and at the hard timeout (the stdin-only line: model, context, limits, no collector segments). A second line would corrupt the status bar.
• Timing: ~30 ms typical. Hard exit at 2 s (setTimeout(...).unref() in src/index.ts); git calls 800 ms each; inline third-party fetches 1.2 s. A slow source only drops its own segment.
• No persistent state in the process; one fresh process per tick.

Files, processes, network

Turn off all network on the official backend with CC_HUD_NO_REFRESH=1. Third-party collectors have no switch; they only run when ANTHROPIC_BASE_URL matches their host.

Environment variables

Boolean switches: "", 0, false mean off; anything else means on (src/env.ts).

Repository map

Development

npm install
npm test             # tsc build + node:test via scripts/test.cjs (the .ts tests need Node ≥ 22.6; dist/ itself runs on ≥ 18)
npm run test:stdin   # build + render one sample line

Render any payload without touching caches or the network:

echo '{"model":{"id":"claude-opus-4-7[1m]"},"effort":{"level":"max"},"context_window":{"used_percentage":42}}' \
  | CC_HUD_NO_REFRESH=1 node dist/index.js | sed 's/\x1b\[[0-9;]*m//g'
# [Opus 4.7 · Max] ████▎░░░░░ 42% (1M)

Exercise the refresher and inspect its cache: node dist/refresh.js claude && cat ~/.cache/cc-hud/claude-plan.json.

Release: bump the version in package.json, .claude-plugin/plugin.json, .claude-plugin/marketplace.json, and root plugin.json; npm test; commit (title ends with (vX.Y.Z)); tag vX.Y.Z; push branch + tag; gh release create; npm publish (package cc-hud).

Codex native footer

Requires Codex CLI ≥ 0.166.0 (checked with codex --version; CC_HUD_CODEX overrides the executable, npm's bin/codex.js is accepted). Install: codex plugin marketplace add WaterTian/cc-hud → codex plugin add cc-hud@cc-hud → new session → run the plugin's setup skill. Update: codex plugin marketplace upgrade cc-hud (installed plugin files refresh too).

Commands — node dist/cli.js <action> codex from the plugin dir or a checkout, or the npm cc-hud bin: setup, check (exit 0 = active), restore, theme, restore-theme; also --help / --version. Errors go to stderr with exit 1. A failed command can leave a backup, an installed asset, or a saved user-layer value (for example, when another layer overrides it); changes are not rolled back automatically. With no arguments the bin is the Claude renderer when stdin is a pipe and prints help on a TTY.

Process model: one temporary codex app-server --stdio per command (cwd and CODEX_HOME = the config dir), JSON-RPC over stdio: initialize → requests → SIGTERM, SIGKILL after 500 ms; 10 s overall deadline. Server notifications and server-initiated requests are ignored; server error bodies are never printed (they can carry private config values). No thread, model, account or usage requests. Normal Codex sessions run with no cc-hud process, hook, MCP or -c flag.

Semantics: Codex's limit percentages are remaining, the Claude HUD's are used. Codex maps 5h / weekly fields to its Limit theme accent (constant.language, fallback storage.type), independent of the numeric value; the user's original theme can make 93% left red. The bundled theme splits constant.numeric (green) from the limit scopes (neutral teal). It does not add usage thresholds: 1% left and 93% left share the same color. Codex controls separators and colors, has no progress bar, and during /compact can briefly show 0% used.

Tests: tests/codex.test.ts drives the CLI against tests/fixtures/fake-codex.cjs, a stand-in app-server with hang / race / write-error / version switches. CC_HUD_CODEX_LIVE_TEST=1 npm test adds a real round-trip against an isolated CODEX_HOME with an offline provider (no auth or model requests); it needs a local Codex ≥ 0.166.0.

Invariants — keep these when changing code

1. One stdout write per tick — go through emit() in src/index.ts; never console.log elsewhere. The hard timeout and the catch-all both emit the stdin-only line, never nothing.
2. No network inside a tick on the official backend — src/claude.ts reads the cache; fetching belongs in refreshClaudePlan(). Inline collectors keep INLINE_TIMEOUT_MS (1.2 s) so the 2 s hard exit is never reached.
3. Unknown is not zero — missing usage renders —%, a failed git status renders ?, a stale gauge / balance / quota gets ~, a finished agent is gone and a dead one times out. Never collapse a failure into a reassuring value.
4. Every IO in try/catch, degrading to a shorter line. The process must exit 0 with one line even when everything fails.
5. Free text is untrusted — anything from stdin, the transcript, git or an API passes through clean() in src/render.ts.
6. Zero dependencies, Node ≥ 18 at runtime — Node built-ins only; no Node 22-only APIs in src/.
7. dist/ is committed — run npm test (which builds) and commit dist/ with the source change.
8. Secrets stay out of argv and logs — curl gets its config on stdin; tokens are never written to the cache.
9. Codex config is written only by the explicit codex commands — three tui.* keys through config/batchWrite with expectedVersion, never by editing TOML text, never from a statusline tick. Every write is re-read and verified; every "ours vs. user-edited" decision errs on the side of leaving the user's value alone.
10. A fixed quota color is not a health signal — native Codex colors limits by theme scope, not remaining percentage. Keep the bundled limit accent neutral, describe the limitation in setup/check, and leave theme selection optional because it also changes syntax highlighting.