CLAUDE.md

Claude HUD is a Claude Code plugin: a status line command that prints a two-line HUD (model, project, git, context, usage), plus opt-in lines for tools, agents, todos, and more.

Commands

npm ci
npm test                           # builds dist/, then runs node --test
npm run test:update-snapshots      # regenerate tests/golden/expected.txt after an intended output change
echo '{"model":{"display_name":"Opus"},"context_window":{"used_percentage":45,"context_window_size":200000}}' | node dist/index.js

How a render works

Claude Code runs the command after each message, /compact, a mode change, a rate-limit reset, or a prompt-cache expiry (debounced 300ms), plus on refreshInterval if set. Each run is a fresh process:

1. stdin.ts reads the payload. It targets Claude Code ≥ 2.1.260 and trusts its fields (version, cost, prompt_cache, session_name, output_style, workspace.repo, rate_limits) instead of deriving them.
2. config.ts loads plugins/claude-hud/config.json plus the per-directory claude-hud.json override. DEFAULT_CONFIG is the schema; a rules table validates each key.
3. index.ts gathers only what enabled elements need, in parallel: the transcript (transcript.ts), git or jj (git.ts, jj.ts), the extra command, memory, auth, config counts, the usage snapshot, the cost ledger, and speed state. All I/O and state writes happen here.
4. render/ turns that into lines without I/O. Each element has one implementation in parts.ts, context.ts, usage.ts, vcs.ts, lines.ts, and activity.ts. expanded.ts and compact.ts only arrange those parts, and ansi.ts measures and wraps.

Invariants

• The default HUD is two lines. New display is opt-in; see the scope section of CONTRIBUTING.md.
• Text from stdin, the transcript, git, or config is untrusted terminal input. Sanitize it (utils/sanitize.ts) before it's printed.
• Rendering is pure: the clock and terminal width are sampled once in renderLines.
• tests/golden.test.js pins end-to-end output. An output change must show up as a reviewed diff to tests/golden/expected.txt.
• dist/ is built by CI on main. Never commit it in a PR.
• README.md and README.zh.md document every key in DEFAULT_CONFIG, and tests/readme-options.test.js enforces it.

Setup

/claude-hud:setup (commands/setup.md) runs scripts/setup.mjs. That copies scripts/statusline.mjs to <config dir>/plugins/claude-hud/ and points statusLine.command at it. The launcher runs the newest installed version, so plugin updates never need setup again. Plugins can't set statusLine themselves, so this step writes the user's settings.json.

Runtime: Node.js 18+ or Bun. Build: TypeScript, ES2022, NodeNext modules.