claude-hud Administrator & Developer Guide

claude-hud is a small (72 files, ~270k characters), pure-TypeScript Claude Code plugin with zero runtime dependencies. It is built into a single ESM bundle (dist/index.js) by the TypeScript compiler, ships through the Claude Code plugin marketplace, and runs as the statusline subprocess on every Claude Code prompt. There is no service, no API, no daemon, and no network call. This guide covers the architecture, every config knob, the deployment shape, the operational characteristics, performance behaviour, the security profile (transcript exposure is the headline concern), the code organisation for contributors, and the integration points (Claude Code stdin schema, git, OS).

It is the companion to the User Guide; usage / recipes / FAQ live there.

1. Architecture Overview

claude-hud is a synchronous-feeling but internally async pipeline that runs once per Claude Code prompt and exits. The driver is main() in src/index.ts (the full file is ~155 lines). Everything else is a leaf function or a small module with a single responsibility.

High-level data flow

                 ┌──────────────────┐
Claude Code  ──► │ stdin (JSON 1x)  │
                 └────────┬─────────┘
                          │
                          ▼
              ┌─────────────────────────┐
              │ src/index.ts: main()    │
              │  1. readStdin()         │
              │  2. parseTranscript()   │
              │  3. countConfigs()      │
              │  4. loadConfig()        │
              │  5. getGitStatus()      │
              │  6. getUsageFromStdin() │
              │  7. parseExtraCmdArg()  │
              │  8. runExtraCmd()       │
              │  9. getClaudeCodeVer()  │
              │ 10. getMemoryUsage()    │
              └────────┬────────────────┘
                       │ RenderContext
                       ▼
            ┌────────────────────────┐
            │ src/render/index.ts    │
            │  render(ctx)           │
            │   ├── renderExpanded() │
            │   │     - project      │
            │   │     - context      │
            │   │     - usage        │
            │   │     - memory       │
            │   │     - environment  │
            │   │     - tools        │
            │   │     - agents       │
            │   │     - todos        │
            │   ├── renderCompact()  │
            │   │     - sessionLine  │
            │   ├── ANSI-aware wrap  │
            │   └── console.log()×N  │
            └────────────────────────┘

The pipeline is fully testable through dependency injection — main() accepts a Partial<MainDeps> overrides bag, and every leaf function the driver calls is also in MainDeps. The tests/ directory exercises this extensively (15 test files, including tests/index.test.js which mocks readStdin, parseTranscript, etc.).

Component inventory

Technology stack

Data flow for the main "render once" workflow

1. Claude Code calls the configured statusLine.command.
2. The command runs node ~/.claude/plugins/claude-hud/dist/index.js with the JSON of the current session piped to stdin.
3. readStdin() reads, parses, and returns a StdinData object (or null if stdin is a TTY or empty within the timeouts).
4. parseTranscript(stdin.transcript_path) either reads from the on-disk JSONL transcript or returns the cached parse result if transcript mtime + size haven't changed.
5. countConfigs(stdin.cwd) reads or returns from cache.
6. loadConfig() reads the user's config.json or returns defaults.
7. getGitStatus(stdin.cwd) runs git subprocesses if gitStatus.enabled.
8. getUsageFromStdin(stdin) extracts the rate-limit windows.
9. parseExtraCmdArg() reads --extra-cmd from process.argv; if present, runExtraCmd() executes it.
10. formatSessionDuration() formats start-time delta.
11. getClaudeCodeVersion() runs only if display.showClaudeCodeVersion.
12. getMemoryUsage() runs only if display.showMemoryUsage AND lineLayout === "expanded".
13. The full RenderContext is handed to render(ctx), which iterates enabled elements in elementOrder, computes line widths with grapheme awareness, wraps to terminal width, and console.log()s each line.
14. The process exits.

There is no shared state across invocations except the on-disk caches.

Note

The driver is wrapped in a single try / catch. Any uncaught error falls through to [claude-hud] Error: <message> on stdout. The plugin is designed to never block Claude Code's prompt cycle, even if every probe fails.

Cache topology

2. System Requirements

Runtime requirements

Build-time requirements (for contributors)

devDependencies live in package.json; there are zero runtime dependencies. The published plugin contains the compiled dist/ plus src/, commands/, and .claude-plugin/.

Disk footprint

The plugin itself is well under 1 MB compiled (the source is ~270 KB, the emitted JS is similar). Caches add up over time but each cache file is small (≤ a few KB):

• transcript-cache/ — one file per distinct transcript path (one per session). Pruning is opportunistic — files become unreadable and are silently rebuilt when transcript mtime/size mismatch.
• config-cache/ — one file per distinct (cwd, claudeConfigDir) pair.

Important

There is no automatic cache cleanup. If you switch between many projects, the config-cache/ and transcript-cache/ directories will grow unboundedly. This is generally fine — files are tiny — but rm -rf ~/.claude/plugins/claude-hud/{config,transcript}-cache is a safe no-op recovery if you ever want to start fresh.

3. Configuration Reference

This section is the complete reference. Every key, every default, every type, every clamp.

Configuration files

Environment variables

claude-hud reads only a small set of env vars; all others are ignored.

CLI flags

The HUD has exactly one user-facing CLI flag.

There are no other flags. The plugin does not respond to --help, --version, or -h.

HudConfig shape (every key)

Top level

gitStatus

display

colors

Each value is a HudColorValue: a HudColorName (dim, red, green, yellow, magenta, cyan, brightBlue, brightMagenta), an integer 0-255, or #rrggbb. Anything else falls back to the default.

Important

mergeConfig() is lenient by design: every invalid value falls back to the default rather than raising. There is no way to tell "config saved but values were rejected" from the HUD itself — set DEBUG=claude-hud and run a smoke test if you suspect silent rejection.

Legacy migrations

migrateConfig() is invoked unconditionally on load.

4. Deployment & Scaling

claude-hud runs as a per-prompt subprocess. It has no notion of "deployment" in the cluster sense — but operators wiring it into shared dev images, devcontainers, or CI smoke tests should know how the install shape behaves.

Production deployment shape

Developer machine
└── ~/.claude/plugins/claude-hud/        (plugin install root)
    ├── dist/index.js                     (compiled entrypoint)
    ├── src/                              (TypeScript sources, shipped)
    ├── commands/configure.md             (slash command source)
    ├── commands/setup.md                 (slash command source)
    ├── .claude-plugin/                   (plugin manifest)
    ├── config.json                       (USER WRITES THIS)
    ├── config-cache/<sha256>.json        (auto)
    ├── transcript-cache/<sha256>.json    (auto)
    ├── .claude-code-version-cache.json   (auto)
    └── .speed-cache.json                 (auto)

The package.json files field intentionally publishes dist/, src/, commands/, and .claude-plugin/ so users can read sources directly from their plugin install — useful both for transparency and for tweaking commands/setup.md locally.

Devcontainer / dotfiles automation

Because the marketplace install requires a Claude Code session, fully unattended provisioning isn't practical. Closest patterns:

1. Pre-bake the install — run /plugin marketplace add and /plugin install once interactively, commit the resulting ~/.claude/plugins/claude-hud/ tree to your dotfiles, and restore it on boot. /claude-hud:setup still has to run interactively to write ~/.claude/settings.json.
2. Pre-bake settings.json — write the statusLine.command entry yourself in your dotfiles/devcontainer Dockerfile, pointing at ~/.claude/plugins/claude-hud/dist/index.js, and skip /claude-hud:setup entirely. The downside: you lose the dynamic version resolution that /claude-hud:setup writes.

Tip

If you go the pre-baked-settings.json route, prepend COLUMNS=$(tput cols) to the command — see issue #416. Without it you'll hit the UNKNOWN_TERMINAL_WIDTH = 40 fallback every time Claude Code spawns the subprocess.

Scaling behaviour

claude-hud runs once per Claude Code prompt. There's nothing to scale in the traditional sense, but performance characteristics matter because the subprocess executes synchronously inside Claude Code's prompt cycle:

• Cold path (no caches): one Node startup, one transcript JSONL read, several git subprocesses, optional claude --version, optional vm_stat. Typical latency: tens to a couple hundred milliseconds on modern hardware.
• Warm path (caches hit): all of the above short-circuit immediately; only the stdin read, the transcript mtime check, and the always-fresh rendering happen. Typical latency: a few milliseconds.

Note

Because Claude Code spawns the statusline subprocess on every prompt, Node.js startup time (typically 30-80 ms) dominates total latency on small projects. There's no way to avoid this without changing Claude Code's plugin protocol — the entire plugin model is "spawn fresh".

Multi-user systems

Each user has their own ~/.claude/plugins/claude-hud/. Caches are per-user. There's no cross-user state; nothing to coordinate.

Disabling without uninstalling

Set ~/.claude/settings.json to remove or comment out the statusLine entry. The plugin remains on disk but never executes.

5. Operations

Health check / smoke test

Run the canonical stdin smoke test from anywhere:

echo '{"model":{"display_name":"Opus"},"context_window":{"current_usage":{"input_tokens":45000},"context_window_size":200000},"transcript_path":"/tmp/test.jsonl"}' \
  | node ~/.claude/plugins/claude-hud/dist/index.js

Expected: a single colourised line (default-config compact would be the session line). Non-zero exit code or missing output indicates a broken install.

The plugin source ships the same smoke test as npm run test:stdin in package.json.

Debug telemetry

There is no metrics endpoint, no log file, no remote telemetry. The only runtime observability is DEBUG=claude-hud (or DEBUG=*) on stderr. Namespaces in use:

Note

Stderr is not captured by Claude Code's statusline pipe — it goes to the parent terminal. That's deliberate (you can keep DEBUG=claude-hud on without breaking the HUD output) but means debug logs aren't preserved across sessions. Pipe stderr to a file in the statusLine.command if you need durable logs.

Routine operations

Operational checklist

• [ ] Plugin installed via /plugin install claude-hud
• [ ] /claude-hud:setup completed (or statusLine entry written manually)
• [ ] node ~/.claude/plugins/claude-hud/dist/index.js < smoke.json returns a styled line
• [ ] claude --version returns a number when run from your shell
• [ ] Terminal supports UTF-8 and ANSI colour
• [ ] If running over a pipe (statusline subprocess), COLUMNS=$(tput cols) is prepended in settings.json (issue #416)
• [ ] On macOS, Claude Code has been fully restarted post-install (issue #375)

Common operational signals

6. Performance

claude-hud is engineered to never noticeably slow Claude Code's prompt cycle, even on large projects.

Performance budget (per prompt)

Caching strategy

The four mtime-keyed caches (transcript, config, version, speed) are the heart of warm-path performance. Cache writes are best-effort (try/catch swallowed) and cache reads validate every key field before trusting the entry.

// From src/transcript.ts: cache invalidation logic
if (
  parsed.transcriptPath !== path.resolve(transcriptPath)
  || parsed.transcriptState?.mtimeMs !== state.mtimeMs
  || parsed.transcriptState?.size !== state.size
) {
  return null;
}

The config-counts cache is more elaborate — it sentinels every input file (CLAUDE.md, settings.json, settings.local.json, .mcp.json, ~/.claude.json) AND the entire rules/ directory tree. A sentinel is {mtimeMs, size}; when any sentinel changes, the cache is rebuilt.

Tip

The cache is stored under ~/.claude/plugins/claude-hud/config-cache/, which lives under the same ~/.claude/ directory whose mtime would otherwise invalidate the cache itself. The implementation deliberately sentinels ~/.claude/CLAUDE.md directly, not the parent directory, to avoid a self-invalidation loop.

Width calculation

The renderer's grapheme-aware width logic (in src/render/index.ts) handles:

• ANSI escape sequences (CSI + OSC) — width 0
• Combining marks, ZWJ, variation selectors — width 0
• Extended pictographic glyphs (most emoji) — width 2
• East Asian wide characters (CJK, Hangul, fullwidth forms) — width 2
• Everything else — width 1

It uses Intl.Segmenter when available (Node 16+), falling back to Array.from() otherwise. The wrapper function (wrapLineToWidth) prefers | and │ separators as wrap points and keeps the leading [model | provider] block together so the badge isn't split.

Resource limits

Note

The 256 KB stdin cap is more than enough for Claude Code's status payload (typically <10 KB). If Claude Code ever ships a much larger payload, the cap would need raising — currently claude-hud would refuse to parse and return null silently.

7. Security

claude-hud is a local-only tool, but it lives at the intersection of Claude Code transcripts (which can contain anything you typed or the model output, including credentials, source code, customer data, PII, internal docs) and the user's shell. Treat it as highly trusted local software and read this section before deploying it to anyone but yourself.

Threat model

Warning

The Claude Code transcript JSONL file (~/.claude/transcripts/...) is the most sensitive piece of data on the machine — it contains the verbatim text of every prompt, every tool call, every model response. claude-hud reads this file. If you are in any environment where transcript content must be protected (regulated industries, customer data, secrets in transit), the whole Claude Code installation needs handling — claude-hud is one of many tools touching it.

Network behaviour

claude-hud makes zero outbound network calls. It does not phone home, does not send telemetry, does not download anything at runtime. The only subprocesses it spawns are local (git, claude, vm_stat, cmd.exe on Windows), plus the user's --extra-cmd if configured. Auditors can confirm with lsof or strace.

Recommended posture

Logging policy

claude-hud writes to two places only:

1. stdout — the HUD output Claude Code displays.
2. stderr — debug messages when DEBUG=claude-hud is set.

It never writes to a third-party log aggregator or external service. Never wire stderr to a third-party log shipper without auditing — debug logs may include cwd paths, MCP server names, configuration counts, and similar metadata.

Caution

If you must enable --extra-cmd, treat the value as code — review exactly what it does. Anything you put after --extra-cmd runs as your user, with your permissions, on every Claude Code prompt. A 3-second cap and 10 KB cap are the only built-in guardrails.

Secrets handling

claude-hud stores no secrets. It does not read API keys. It does not read .env files. It does not parse environment variables for tokens. The only env vars consulted are listed in Section 3 (none secret).

CVE / disclosure

The repo includes a SECURITY.md for vulnerability reporting. Use that file's contact path rather than filing a public issue.

8. Developer Internals

This section is for contributors and operators forking the plugin.

Repository layout

claude-hud/
├── .editorconfig
├── .gitignore
├── .claude-plugin/         (Claude Code plugin manifest, shipped to users)
├── CHANGELOG.md
├── CLAUDE.README.md         (notes on running Claude Code against this repo)
├── CLAUDE.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE                  (MIT)
├── MAINTAINERS.md
├── README.md
├── RELEASING.md
├── SECURITY.md
├── SUPPORT.md
├── TESTING.md
├── claude-hud-preview-*.png
├── package.json
├── package-lock.json
├── tsconfig.json
├── commands/
│   ├── configure.md         (slash command source: /claude-hud:configure)
│   └── setup.md             (slash command source: /claude-hud:setup)
├── src/
│   ├── claude-config-dir.ts
│   ├── config-reader.ts
│   ├── config.ts
│   ├── constants.ts
│   ├── cost.ts
│   ├── debug.ts
│   ├── extra-cmd.ts
│   ├── git.ts
│   ├── index.ts             (entry point)
│   ├── memory.ts
│   ├── speed-tracker.ts
│   ├── stdin.ts
│   ├── transcript.ts
│   ├── types.ts
│   ├── version.ts
│   ├── i18n/
│   │   ├── en.ts
│   │   ├── index.ts
│   │   ├── types.ts
│   │   └── zh.ts
│   ├── render/
│   │   ├── agents-line.ts
│   │   ├── colors.ts
│   │   ├── index.ts
│   │   ├── session-line.ts
│   │   ├── todos-line.ts
│   │   ├── tools-line.ts
│   │   └── lines/
│   │       ├── cost.ts
│   │       ├── environment.ts
│   │       ├── identity.ts
│   │       ├── index.ts
│   │       ├── memory.ts
│   │       ├── project.ts
│   │       ├── session-tokens.ts
│   │       └── usage.ts
│   └── utils/
│       └── terminal.ts
└── tests/
    ├── *.test.js            (14 test files)
    └── fixtures/
        ├── transcript-basic.jsonl
        ├── transcript-render.jsonl
        └── expected/
            └── render-basic.txt

Build, test, develop

# Install dev dependencies
npm install

# One-shot build
npm run build              # tsc

# Watch mode while editing
npm run dev                # tsc --watch

# Run tests against compiled dist/
npm test                   # builds, then node --test

# Run with coverage
npm run test:coverage      # c8 + node --test

# Manual stdin smoke test (uses default config)
npm run test:stdin

The prepare script is intentionally absent — the plugin marketplace ships the prebuilt dist/ directly. CI / publishing pipelines should run tsc before tagging releases.

Module reference (every HIGH-priority module)

src/index.ts — driver

The main() function takes Partial<MainDeps> for testing. MainDeps covers every external function (readStdin, parseTranscript, etc.) plus now: () => number and log: (...args: unknown[]) => void. The default deps are the real implementations. Tests override one or more deps to assert specific paths.

The "TTY guard" at the bottom of the file:

const scriptPath = fileURLToPath(import.meta.url);
const argvPath = process.argv[1];
const isSamePath = (a: string, b: string): boolean => {
  try {
    return realpathSync(a) === realpathSync(b);
  } catch {
    return a === b;
  }
};
if (argvPath && isSamePath(argvPath, scriptPath)) {
  void main();
}

ensures main() only runs when the file is the entry point — it is safe to import main and formatSessionDuration from tests without triggering a side-effecting render.

src/stdin.ts — JSON ingestion

Reads stdin with three timeouts (first byte, idle, total bytes). Idle timeout is the unusual one: it allows Claude Code to dribble JSON in multiple chunks, but parses as soon as the JSON is complete. If parsing succeeds, it short-circuits without waiting for stream end.

Native context percent (Claude Code 2.1.6+) wins over manual calculation in both getContextPercent and getBufferedPercent. The Bedrock provider is detected by model id substring anthropic.claude-; a friendly display label like Claude Sonnet 4 is reconstructed via normalizeBedrockModelLabel.

src/transcript.ts — JSONL streaming parse

Streams the JSONL file via readline, accumulates session token totals across all assistant messages (message.usage). Tool / agent / todo state is tracked via Maps keyed by tool-use id. The TodoWrite/TaskCreate/TaskUpdate flow is non-trivial:

• TodoWrite rewrites the entire todo list. To preserve in-progress state when items are reordered, the parser builds a content-based reverse map (content -> task ids) before clearing, then re-establishes task-id-to-index mappings for items whose content matches.
• TaskCreate appends a todo with the supplied subject/description and registers either input.taskId or the block id as the lookup key.
• TaskUpdate resolves the index via the lookup map, with a fallback for numeric-string task ids that act as 1-based indices.

Issue #454 documents a duplicate-content edge case in this logic.

src/config-reader.ts — countConfigs()

The most complex single function in the codebase. Walks user scope and project scope, dedupes scopes that overlap (when cwd/.claude resolves to ~/.claude), counts CLAUDE.md files at multiple known paths, recursively counts rules markdown, computes MCP server set differences, applies disabled MCP filters, and writes a sentinel-keyed cache.

The cross-platform path comparison (pathsReferToSameLocation) tries:

1. Normalise both paths (resolve, lowercase on Windows).
2. If equal, return true.
3. Otherwise, try realpath on both and compare the results.

This catches symlink chains and \\ vs / Windows path variants.

src/git.ts — getGitStatus()

Executes 5 git subprocesses in sequence, each with execFile (no shell interpolation). Tolerates missing remotes, no upstream, binary diffs (skipped via Number.isNaN(added) || Number.isNaN(deleted) check), and renames (old -> new parsed from porcelain). Returns null for any non-git directory.

src/render/index.ts — width-aware rendering

Three responsibilities:

1. Dispatch on lineLayout to either renderExpanded or renderCompact.
2. Run the grapheme-aware visual-length and wrapping logic.
3. Emit ${RESET}${line} to console.log for each visible line.

The terminal width resolution chain is process.stdout.columns -> process.stderr.columns -> process.env.COLUMNS -> UNKNOWN_TERMINAL_WIDTH (40). Stderr is the secret weapon — when Claude Code pipes stdout, the real terminal width is still readable from stderr.

src/render/lines/* — eight one-job renderers

Every line renderer takes RenderContext and returns string | null. They never throw, never share state, never mutate the context. Each is ≤200 lines. This makes them trivially unit-testable: pass a synthetic context, assert on the output string.

The compact-layout session-line.ts is the exception — it's a much larger renderer that combines what would otherwise be 8 lines into one, in a specific order, with optional separators. Its complexity is driven by feature-toggle interactions rather than logic depth.

src/render/colors.ts — ANSI factory

Maintains the named-preset table, the hex-to-truecolor encoder, and threshold-aware colour pickers (getContextColor, getQuotaColor) that drive the bar styling. coloredBar and quotaBar are the bar generators — both clamp percentage to [0,100] and width to non-negative integers, then emit █ for filled cells and dim ░ for empty.

Code patterns and conventions

• Pure functions everywhere except the driver and the renderer's I/O. No classes, no global mutable state outside version.ts's in-memory cache fields.
• Explicit return-null-on-failure. Every probe returns null (or undefined) on any error rather than throwing. The driver and the renderers all handle null gracefully.
• Lenient validators. mergeConfig() clamps invalid values to the default rather than rejecting. Bias is toward "render something" over "fail loudly" — a HUD that crashes is worse than a HUD that shows defaults.
• Test seams via dependency injection. Every external call is injectable. The compiled JS in dist/ is what tests import — this catches type → JS gaps. Tests live in tests/*.test.js and use Node's built-in node:test.
• mtime + size sentinels for caches. Every cache validates by re-stat'ing inputs; never by TTL alone. Trades a few extra stat syscalls for instant invalidation.
• No bundler. tsc compiles to ESM dist/, period. Imports use .js extensions in source (Node ESM convention) so the same paths work pre- and post-compile.

Testing strategy

The test suite is comprehensive for its size. 14 test files cover:

• index.test.js — driver, with happy paths, error paths, dependency injection, and entry-point isolation.
• config.test.js — mergeConfig validation, migration, color value acceptance.
• core.test.js — small primitives.
• git.test.js — porcelain parsing, numstat parsing, file stats, rename handling.
• i18n.test.js — locale lookup with fallback chain.
• memory.test.js — vm_stat parsing, formatBytes, dependency injection of MemoryReader.
• render.test.js — full render output across layouts and toggles.
• render-width.test.js — grapheme + ANSI width edge cases (emoji, CJK, ZWJ, control chars, OSC sequences).
• speed-tracker.test.js — sliding-window math.
• stdin.test.js — timeout / parse / size / TTY behaviours.
• terminal.test.js — adaptive bar width.
• version.test.js — binary path resolution, .cmd/.bat invocation, cache key behaviour.
• extra-cmd.test.js — argv parsing, sanitisation, JSON parse, label truncation.
• integration.test.js — end-to-end render against fixture transcripts.

The fixture files live at tests/fixtures/transcript-basic.jsonl, tests/fixtures/transcript-render.jsonl, and the expected output is captured in tests/fixtures/expected/render-basic.txt. Update fixtures with npm run test:update-snapshots.

Potential improvements

These are ideas surfaced by the open issues and reading the source — not endorsed roadmap items.

• Pricing-table autoupdate (issue #452). Move the model→pricing table out of src/cost.ts and either fetch it on first run or expose a config-level override map.
• Compact-layout regression (issues #408, #412). v0.0.12's compact rendering diverges from v0.0.11; trace the regression to the session-line.ts rewrite.
• COLUMNS injection in setup (issue #416). Update commands/setup.md to always prepend COLUMNS=$(tput cols) to the written statusLine.command. Also worth detecting at runtime when the fallback fires and warning to stderr.
• Cache eviction. Add a soft cap (e.g. 100 entries) to transcript-cache/ and config-cache/ with LRU eviction.
• Codex-hud (issue #215). Refactor src/stdin.ts types into a pluggable adapter so other Claude-Code-style tools can be wired up.
• Native-vs-cache for claude --version (issue #429). Hash the Claude Code binary content (or its --version output) instead of trusting mtime alone.

Contributing

The repo includes CONTRIBUTING.md, MAINTAINERS.md, and RELEASING.md. The project is MIT-licensed and accepts external PRs. Test coverage and type strictness are non-negotiable — every PR runs the full test suite via Node's built-in test runner.

Note

Type changes that touch src/types.ts (especially StdinData) require updating both the i18n message catalog (src/i18n/types.ts) and the renderer expectations. The compiler will catch most of this, but the render fixtures need a manual snapshot update.

9. Integration Points

Claude Code (the primary integration)

claude-hud consumes JSON from Claude Code's statusline subprocess contract. The shape it cares about (a subset of what Claude Code emits) lives in src/types.ts's StdinData interface:

interface StdinData {
  transcript_path?: string;       // Path to the JSONL transcript
  cwd?: string;                   // Working directory of the session
  model?: {
    id?: string;                  // e.g. "claude-opus-4-6"
    display_name?: string;        // e.g. "Opus 4.6 (1M context)"
  };
  context_window?: {
    context_window_size?: number;
    current_usage?: {
      input_tokens?: number;
      output_tokens?: number;
      cache_creation_input_tokens?: number;
      cache_read_input_tokens?: number;
    } | null;
    used_percentage?: number | null;       // Claude Code 2.1.6+
    remaining_percentage?: number | null;  // Claude Code 2.1.6+ (unused but typed)
  };
  cost?: {
    total_cost_usd?: number | null;
    total_duration_ms?: number | null;     // typed but unused by HUD
    total_api_duration_ms?: number | null; // typed but unused by HUD
    total_lines_added?: number | null;     // typed but unused by HUD
    total_lines_removed?: number | null;   // typed but unused by HUD
  } | null;
  rate_limits?: {
    five_hour?: { used_percentage?: number | null; resets_at?: number | null } | null;
    seven_day?: { used_percentage?: number | null; resets_at?: number | null } | null;
  } | null;
}

Every field is optional and every probe handles missing values gracefully.

Claude Code transcript JSONL

Read by parseTranscript() line-by-line. The shape it consumes:

interface TranscriptLine {
  timestamp?: string;          // ISO 8601
  type?: string;               // 'assistant', 'custom-title', etc.
  slug?: string;               // Auto-generated session slug
  customTitle?: string;        // /rename custom title
  message?: {
    content?: ContentBlock[];
    usage?: {
      input_tokens?: number;
      output_tokens?: number;
      cache_creation_input_tokens?: number;
      cache_read_input_tokens?: number;
    };
  };
}

interface ContentBlock {
  type: string;                // 'tool_use' | 'tool_result' | text
  id?: string;
  name?: string;               // e.g. 'Read', 'Bash', 'TodoWrite', 'Task'
  input?: Record<string, unknown>;
  tool_use_id?: string;
  is_error?: boolean;
}

Special-case tool names: Task/Agent populate the agents map; TodoWrite/TaskCreate/TaskUpdate drive todos; Read/Write/Edit extract file_path or path; Glob/Grep extract pattern; Bash extracts the first 30 chars of command. Everything else lands in the generic tools map.

Claude Code settings.json

Read indirectly through countConfigs() to count MCPs and hooks. The relevant fields:

{
  "mcpServers": {
    "<name>": { /* opaque config */ }
  },
  "hooks": {
    "<name>": { /* opaque config */ }
  },
  "outputStyle": "tech-leader",
  "disabledMcpServers": ["names"],
  "disabledMcpjsonServers": ["names"]
}

Where the parser looks:

Git CLI

All run via execFile (no shell). Timeouts: 1s for the first three, 2s for numstat, 1s for the last two.

claude CLI

getClaudeCodeVersion() runs claude --version (or cmd.exe /d /s /c "<path> --version" on Windows for .cmd/.bat shims) with a 2-second timeout. Output is parsed by _parseClaudeCodeVersion's regex: /\d+(?:\.\d+)+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?/. The result is cached on disk keyed by binary path + mtime. claude must be on PATH and executable; on Windows it tries every PATHEXT extension.

macOS vm_stat

getMemoryUsage() runs /usr/bin/vm_stat (5-second timeout, encoding utf8) and parses Pages active, Pages wired down, and page size of N bytes to compute used memory. Falls back to os.totalmem() / os.freemem() on parse failure. Other platforms use the os module directly.

OSC-8 hyperlinks

Both the project label and the git branch (when GitHub remote exists) are wrapped in OSC-8 escape sequences:

ESC ] 8 ; ; <uri> ESC \ <visible text> ESC ] 8 ; ; ESC \

In supporting terminals (iTerm2, modern Windows Terminal, kitty, recent gnome-terminal), this makes the project name a clickable file://<cwd> link and the branch name a clickable https://github.com/<owner>/<repo>/tree/<branch> link.

--extra-cmd user integration

The single user-visible CLI flag. The contract:

• Parsed from process.argv by parseExtraCmdArg() — supports both --extra-cmd value and --extra-cmd=value.
• Executed via child_process.exec with a 3-second timeout and 10 KB stdout cap.
• Output must be JSON of the shape { "label": "string" }. Any other shape returns null.
• The label value is sanitised (CSI/OSC/control/bidi stripped) and truncated to 50 chars before display.

Important

--extra-cmd runs through the user's shell. The repo comments explicitly note this is intentional user input — shell injection is not a concern only because the user types their own command. Never accept a --extra-cmd value from an untrusted source.

Integration table (one-liner summary)

There are no other external integrations — no HTTP, no IPC, no inter-process state, no telemetry.