jarrodwatts/claude-hud

Claude HUD is a real-time statusline tool for Claude Code that provides a customizable, modular display of agent activity, usage metrics, and system context. It replaces a legacy terminal interface with a secure, i18n-enabled architecture that tracks costs, token usage, and authentication details. The system allows users to configure layout, colors, and specific data segments to adapt to their terminal environment and preferences.

The application now supports Simplified Chinese (zh-Hans) and Traditional Chinese (zh-Hant) in addition to English. This change introduces a new internationalization layer in src/i18n that maps language tags (including aliases like 'zh' and 'zh-TW') to canonical locales, provides translated strings for UI labels, status messages, and time formats, and includes a helper for placeholder interpolation to handle layout differences between languages.

src/i18n · high confidence

The i18n module now includes built-in translations for English, Simplified Chinese (zh-Hans), and Traditional Chinese (zh-Hant). Users will see localized labels, status messages, and format strings (such as time and token counts) in their preferred language, with automatic fallback to English if a specific key is missing.

dist/i18n · high confidence

This change introduces the core source files for the Claude HUD v2 status line, replacing the previous implementation with a modular architecture. It adds a robust configuration system (src/config.ts) supporting extensive customization of the HUD layout, colors, and display modes (e.g., model format, effort level, time format). The update includes new modules for authentication derivation (src/auth.ts), cost estimation with native stdin support (src/cost.ts), daily cumulative cost tracking (src/daily-cost.ts), and context caching (src/context-cache.ts). Security is significantly hardened through input sanitization for display text, strict validation of config keys, secure file permissions for cache/ledger files, and opt-in requirements for potentially risky features like extra commands. The diff also adds support for Git status display, MCP server counting, and improved handling of Claude Code stdin data, including effort levels and model pricing.

src · high confidence

The HUD now displays the current authentication method and user account in the status line, with the auth segment formatted according to configurable display settings (showAuth, showAuthUser, authUserLength). To support this, the system resolves the Claude config directory path, supporting the CLAUDE\_CONFIG\_DIR environment variable and tilde expansion, and caches the derived auth info against the config file's identity (mtime, size, etc.) to minimize read overhead on every interaction tick.

dist · high confidence

Added a suite of utility functions in src/utils to improve terminal output and security. format.ts provides human-readable token counts and context-window display formatting. hyperlinks.ts and sanitize.ts introduce safe hyperlink generation with strict protocol validation (allowing only https: and file:) and text sanitization to strip dangerous control characters, ANSI escapes, and bidirectional overrides, preventing escape injection and layout corruption. terminal.ts adds robust terminal width detection (prioritizing the COLUMNS environment variable) and adaptive progress bar sizing. truncate.ts offers a simple string truncation helper with ellipsis support.

src/utils · high confidence

The status line has been refactored into a modular system of individual renderers (e.g., \added-dirs\, \advisor\, \compactions\, \cost\, \environment\, \identity\, \memory\, \project\) that are composed into a single line. This change introduces several new display capabilities: users can now see added directories, advisor model information, compaction counts, cost estimates, and environment configuration counts. The context display now supports a token breakdown (input and cache usage) when context is critical, and the memory line is available in expanded layout. Additionally, the system supports custom lines, session names, Claude Code version display, output speed, and authentication segments, all configurable via the \display\ configuration object.

dist/render/lines · high confidence

The statusline rendering has been restructured into a modular system of dedicated line components (identity, project, usage, cost, memory, session time, prompt cache, compactions, advisor, added directories, and environment). This change introduces granular, opt-in configuration for each segment, allowing users to enable or disable specific displays such as session names, model-scoped usage, daily cumulative costs, prompt cache expiry, and memory usage. The new layout supports expanded multi-line modes and configurable segment ordering, providing a cleaner, more customizable HUD that adapts to terminal width and user preferences.

src/render/lines · high confidence

The main TUI entry point file (tui/src/index.tsx) has been deleted. This removes the previous implementation of the Claude HUD interface, including its event processing logic for tools, agents, and context, as well as the command-line argument handling for session and FIFO paths.

tui/src · high confidence

The \event-reader.ts\ module, which previously handled reading HUD events from a named pipe (FIFO) and emitting them, has been removed. Additionally, the \types.ts\ file containing the \HudEvent\, \ToolEntry\, \TodoItem\, \ModifiedFile\, \AgentEntry\, \ContextState\, and \AppState\ interfaces has been deleted. This change eliminates the underlying data structures and the file-based event ingestion mechanism used by the TUI component.

tui/src/lib · high confidence

The AgentList, ContextMeter, McpStatus, ModifiedFiles, TodoList, and ToolStream components have been removed from the TUI. These components previously displayed real-time status information such as agent states, context token usage, MCP server connections, modified files, todo items, and tool execution streams. Their removal indicates a shift away from this specific inline status display approach in the terminal user interface.

tui/src/components · high confidence

The HUD now displays a dedicated line showing the status, model, and duration of active and recently completed agents, with model names automatically compacted to their family and version (e.g., 'claude-opus-4-8' becomes 'opus-4'). The first line of the HUD supports configurable ordering of segments via the new \orderFirstLineParts\ logic, allowing users to customize the sequence of project, git, and other elements. Additionally, usage reset times can now be displayed in relative, absolute, or combined formats, and the color system has been expanded to support custom overrides for model, project, and git labels.

dist/render · high confidence

The HUD has been rebuilt with a modular architecture, introducing distinct renderers for agents, skills, MCPs, and todos alongside the existing session and usage lines. This change brings a new 2-line default layout that separates the session context from the agent/activity status, and adds extensive configurability including custom element ordering, color overrides for all segments, and support for 256-color and hex values. The display now features improved handling of narrow terminals and CJK characters, configurable reset time formats (absolute/relative/both), and opt-in displays for agent history, skills, MCPs, and project paths.

src/render · high confidence

The build process now includes a dedicated script to safely clean the distribution directory, ensuring no stale artifacts remain. Concurrently, the legacy shell-based session management scripts (session-start, capture-event, cleanup) have been removed, indicating a shift away from the previous FIFO-based event capture and terminal-splitting logic implemented in these files.

scripts · high confidence

Added new test suites for the authentication module (auth.test.js), configuration system (config.test.js), context window caching (context-cache.test.js), cost estimation (cost-coverage.test.js, daily-cost.test.js), and core HUD functionality (core.test.js, effort.test.js, env-disable.test.js, external-usage.test.js). These tests verify auth info derivation and caching, config validation and defaults, context fallback logic, cost calculations for various models and providers, daily cost tracking, and environment variable handling.

tests · high confidence

This change introduces the initial version (0.8.0) of the 'claude-hud' package, a real-time statusline HUD for Claude Code. It establishes the project's dependency tree, specifying a Node.js engine requirement of \>=18.0.0 and updating development dependencies to @types/node ^26.2.0, c8 ^11.0.0, and TypeScript ^7.0.2. Additionally, the legacy 'tui' sub-package (claude-hud-tui) and its associated dependencies (ink, react, minimist) have been removed from the repository.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 49 → 68 (+19.2)
• Rubric changed (rubric-2026.08.15 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 59 → 66 (+7.3)
• Architecture 92 (new)
• Maturity 67 → 66 (-0.7)
• Readiness 35 → 66 (+31.5)
• Security 66 → 76 (+9.2)

• Boundary-crossing change coupling: en.ts ↔ environment.ts (src/i18n/en.ts)
• Boundary-crossing change coupling: en.ts ↔ session-line.ts (src/i18n/en.ts)
• Boundary-crossing change coupling: types.ts ↔ environment.ts (src/i18n/types.ts)
• Boundary-crossing change coupling: types.ts ↔ session-line.ts (src/i18n/types.ts)
• Change coupling: config.ts ↔ environment.ts (src/config.ts)
• Change coupling: config.ts ↔ index.ts (src/config.ts)
• Change coupling: environment.ts ↔ project.ts (src/render/lines/environment.ts)
• Change coupling: environment.ts ↔ session-line.ts (src/render/lines/environment.ts)
• Change coupling: identity.ts ↔ session-line.ts (src/render/lines/identity.ts)
• Change coupling: index.ts ↔ index.ts (src/render/index.ts)
• Dimension evaluation failed
• FileTooLong: tests/context-cache.test.js (tests/context-cache.test.js)
• FileTooLong: tests/core.test.js (tests/core.test.js)
• FileTooLong: tests/index.test.js (tests/index.test.js)
• FileTooLong: tests/render-width.test.js (tests/render-width.test.js)
• High CVE: [GHSA redacted] (package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• High: security finding (details withheld)
• High: security finding (details withheld)
• …and 21 more

• Change coupling: project.ts ↔ session-line.ts (src/render/lines/project.ts)
• Change coupling: usage.ts ↔ session-line.ts (src/render/lines/usage.ts)
• Change-coupling hub: identity.ts → config.ts, usage.ts, session-line.ts (src/render/lines/identity.ts)
• Dependency hygiene PARTLY measured — npm pinning read, dependency currency not (the committed lockfile resolved no direct production dependency)
• Documentation: no installation or build instructions (README.md)
• FileTooLong: src/config.ts (src/config.ts)
• FileTooLong: src/transcript.ts (src/transcript.ts)
• FunctionTooLong: config.mergeConfig (src/config.ts)
• FunctionTooLong: index.main (src/index.ts)
• FunctionTooLong: session-line.renderSessionLine (src/render/session-line.ts)
• FunctionTooLong: transcript.parseTranscript (src/transcript.ts)
• FunctionTooLong: transcript.processEntry (src/transcript.ts)
• Further sole-owners (lower concentration)
• High CVE: [GHSA redacted] (package-lock.json)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• …and 71 more

• 33 commits — 25 feature/other, 8 fixes

• (root) — 13 commits
• dist/render — 5 commits
• (repo) — 2 commits
• .github/workflows — 2 commits
• dist/i18n — 2 commits
• src/i18n — 2 commits
• tests/git.test.js — 2 commits
• dist/config.d.ts — 1 commit
• src/auth.ts — 1 commit
• src/config.ts — 1 commit
• src/render — 1 commit
• tests/format-reset-time.test.js — 1 commit

• fix: Merge pull request #706 from jarrodwatts/codex/fix-agents-completed-display
• fix: fix(agents): expire stale completed entries
• fix: fix(cache): refresh the prompt cache clock when a request starts (#721)
• fix: fix(config): close TOCTOU between config validation and read (#732)
• fix: fix: agents, git locks, cache wording, and zh docs (#737)
• fix: fix: apply clock settings to compact usage windows
• fix: fix: prevent orphaned Git processes on Windows
• fix: prompt cache fixes/display - don't count subagents, detect the TTL, show expiry time (#702)
• change: Merge pull request #707 from jarrodwatts/codex/release-0.7.1
• change: build(deps-dev): bump @types/node from 26.1.2 to 26.2.0 (#711)
• change: build: compile dist/ [auto]
• change: build: compile dist/ [auto]
• change: build: compile dist/ [auto]
• change: build: compile dist/ [auto]
• change: build: compile dist/ [auto]
• change: build: compile dist/ [auto]
• change: build: compile dist/ [auto]
• change: build: compile dist/ [auto]
• change: ci: retain actionable Windows test tail
• change: ci: surface Windows Git test failures
• …and 13 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

jarrodwatts/claude-hud was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.