How jarrodwatts/claude-hud works
Claude HUD is a Claude Code plugin that runs as a statusline renderer, not as a separate UI app. The core architectural boundary is between Claude Code, which streams session state into the plugin over stdin, and Claude HUD, which transforms that state into a compact terminal status line on stdout.
High-level architecture
There are three main parts:
1. Plugin packaging and command surface
2. Runtime data collection and state synthesis
3. Rendering/output
The repository is TypeScript-first, with compiled JavaScript checked into dist/ for distribution. That means the architecture is split between src/ as the canonical source and dist/ as the shipped artifact used by the Claude Code plugin system.
Main runtime flow
The data flow is:
• Claude Code launches the HUD as a statusline process.
• Claude Code sends JSON status updates on stdin.
• Claude HUD reads session/config/transcript information, plus local environment data.
• It derives current session state such as:
- current model/provider label
- project path
- git branch and repo status
- context window usage
- rate-limit usage
- active tools
- running agents
- todo progress
- optional memory and session metadata
• The renderer assembles one or more status lines.
• The final string is written to stdout for Claude Code to display below the input box.
This is a classic stream-in / stream-out terminal integration, with no browser, server, or separate daemon.
Subsystems
1. Plugin and command packaging
Relevant files:
• .claude-plugin/plugin.json
• .claude-plugin/marketplace.json
• commands/setup.md
• commands/configure.md
This repo is packaged as a Claude Code plugin. The plugin metadata and marketplace manifest define how it is discovered and installed. The command markdown files define the slash commands surfaced to the user:
• /claude-hud:setup
• /claude-hud:configure
These are user-facing orchestration commands, not part of the rendering loop. Their job is to create or update the Claude Code configuration and the plugin config file under the user’s Claude directory.
2. Configuration subsystem
Relevant source:
• src/config.ts
• src/config-reader.ts
• src/claude-config-dir.ts
• src/constants.ts
• src/types.ts
This layer loads and validates HUD configuration from the Claude plugin config directory, which the README identifies as:
• ~/.claude/plugins/claude-hud/config.json
It also manages defaults and version-aware settings such as:
• lineLayout
• pathLevels
• elementOrder
• git display toggles
• display feature flags
• color overrides
• context/usage thresholds
This subsystem is the main boundary between persisted user customization and live session rendering. The renderer consumes normalized config; it does not need to know where the config came from.
3. Claude Code stdin / transcript ingestion
Relevant source:
• src/stdin.ts
• src/transcript.ts
• src/debug.ts
This is the ingestion layer for runtime session data coming from Claude Code. The README indicates Claude Code emits:
• stdin JSON
• transcript JSONL for tools, agents, and todos
That makes this repo dependent on two Claude Code data channels:
• a structured stdin stream for session metadata and rate limits
• transcript/event data for activity history
The transcript parser is important because several HUD lines are not direct status values, but derived activity summaries:
• tool activity
• agent status
• todo progress
4. Session telemetry and derivation
Relevant source:
• src/speed-tracker.ts
• src/memory.ts
• src/version.ts
• src/git.ts
• src/extra-cmd.ts
This layer computes secondary metrics from raw inputs and local system information.
Key responsibilities:
• Speed tracking: derives output token speed over time
• Memory usage: reads approximate local RAM usage when enabled
• Version reporting: exposes the installed Claude Code version when configured
• Git state: resolves branch name and status from the current repo
• Extra commands: supports setup/configure actions that mutate config or Claude Code state
This is the main place where the HUD crosses into local machine boundaries:
• filesystem for project path and config
• git repository state via the local Git executable/repo metadata
• OS memory information
• local Claude Code installation/version
5. Rendering subsystem
Relevant source:
• src/render/index.ts
• src/render/colors.ts
• src/render/agents-line.ts
• src/render/session-line.ts
• src/render/todos-line.ts
• src/render/tools-line.ts
• src/render/lines/index.ts
• src/render/lines/project.ts
• src/render/lines/environment.ts
• src/render/lines/identity.ts
• src/render/lines/memory.ts
• src/render/lines/usage.ts
Rendering is organized as composable line builders. There are two levels of formatting logic:
• element-level renderers for individual concepts like project, usage, identity, environment, memory
• activity-line renderers for tools, agents, todos, and session state
This structure supports the two display modes described in the README:
• expanded: multiple lines with configurable element order
• compact: condensed single-line output
The rendering subsystem also owns color selection and visual thresholds, such as:
• context bar color changes at warning/critical thresholds
• usage bars and subscriber usage thresholds
• custom color mappings
The renderer is the final boundary before stdout; it receives normalized state objects and returns terminal-safe strings.
6. Utility layer
Relevant source:
• src/utils/terminal.ts
• src/debug.ts
• src/constants.ts
• src/types.ts
This is shared support code for terminal formatting, environment handling, constants, and type definitions. It is not a separate subsystem so much as the glue that keeps ingestion, derivation, and rendering consistent.
Important architectural boundaries
Claude Code boundary
Claude Code is the primary external runtime. Claude HUD does not poll APIs directly for core session status. Instead, it relies on Claude Code’s statusline contract and transcript output.
Git boundary
Git information is read from the local repository. Git status display is optional and only meaningful when the current working directory is inside a repo.
Local machine boundary
Optional features like system memory usage and installed Claude Code version depend on the local host environment, not on Claude Code itself.
User config boundary
The user’s config file under the Claude plugin directory controls presentation, thresholds, and feature toggles. This keeps runtime state separate from persistent preferences.
Build, distribution, and release architecture
Relevant files:
• package.json
• tsconfig.json
• dist/
• .github/workflows/build-dist.yml
• .github/workflows/ci.yml
• .github/workflows/release.yml
• .github/workflows/claude.yml
• .github/workflows/release.yml
The repo is built as a Node.js/Bun-compatible TypeScript package, then emitted into dist/ for plugin consumption. The checked-in dist/ directory suggests the published artifact is committed and used directly by the plugin runtime.
The GitHub Actions workflows indicate separate concerns:
• CI validation
• distribution build
• release automation
• Claude-related automation for plugin workflow
Testing architecture
Relevant files:
• tests/*.test.js
• tests/fixtures/
• TESTING.md
Tests cover the main subsystems independently:
• config parsing
• git state extraction
• rendering
• stdin handling
• transcript parsing
• speed tracking
• version reporting
• terminal behavior
• integration behavior
The fixture-based tests for transcript and rendering are especially important because they validate the HUD as a deterministic formatter of streamed Claude Code events.
How to think about the diagram
If you are drawing the architecture, the clearest representation is:
• Claude Code at the top as the event source and host
• Plugin command/config layer on the side for setup and customization
• Runtime core in the middle, split into:
- input parsing
- state derivation
- rendering
• External local dependencies around the runtime:
- git
- filesystem
- OS memory
- Claude Code installation/version
• stdout statusline output as the final sink back into Claude Code’s UI
In short, Claude HUD is a terminal-native, event-driven statusline plugin with a clear separation between configuration, live session ingestion, derived telemetry, and presentation.
Main entry points: config.ts Config loader · src/index.ts Source entry · render/index.ts Renderer · stdin.ts Stdin ingest
Components 20
Plugin packaging
Discovery, install, and user commands for Claude Code.
- Plugin manifest · Claude Code plugin descriptor and marketplace entry.
.claude-plugin/plugin.json - Marketplace info · Marketplace registration and install metadata.
.claude-plugin/marketplace.json - Setup command · Slash command that bootstraps Claude Code and HUD config.
commands/setup.md - Configure command · Slash command for updating HUD settings.
commands/configure.md
Runtime core
Live session ingestion, state synthesis, and statusline rendering.
- Config loader · Loads defaults, validates settings, and resolves effective HUD configuration.
src/config.ts - Config reader · Reads persisted plugin configuration from the Claude config directory.
src/config-reader.ts - Claude config dir · Resolves the plugin configuration location under the user Claude directory.
src/claude-config-dir.ts - Stdin ingest · Parses structured status updates streamed from Claude Code on stdin.
src/stdin.ts - Transcript parser · Parses transcript JSONL for tools, agents, and todo activity.
src/transcript.ts - Telemetry · Derives session metrics such as speed, memory, version, and git state.
- Speed tracker · Computes output speed over time from streaming activity.
src/speed-tracker.ts - Renderer · Coordinates line assembly and final terminal-safe output.
src/render/index.ts - Line builders · Builds project, identity, environment, usage, memory, tools, agents, session, and todo lines.
src/render/lines/index.ts - Terminal utils · Shared terminal formatting and width handling utilities.
src/utils/terminal.ts
Local dependencies
External inputs the HUD reads from the host machine and Claude Code.
- Claude Code · Launches the HUD, streams session state, and consumes the rendered statusline.
- Git state · Reads branch and repository status from the local git checkout.
src/git.ts - Memory probe · Collects optional local memory usage information.
src/memory.ts - Version probe · Reports installed Claude Code version when enabled.
src/version.ts
Build and release
TypeScript source, checked-in dist artifact, and automation.
- Source entry · TypeScript entrypoint wiring the runtime together.
src/index.ts - Dist bundle · Checked-in compiled JavaScript used by the plugin runtime.
dist/index.js
Connections 23
- Claude Code → Stdin ingest: status stream · Sends JSON session updates over stdin.
- Claude Code → Transcript parser: transcript events · Provides JSONL activity history.
- Claude Code → Plugin manifest: loads plugin · Discovers the plugin through Claude Code metadata.
- Plugin manifest → Marketplace info: publish metadata · Uses marketplace registration for distribution.
- Setup command → Config loader: writes config · Bootstraps or updates HUD settings.
- Configure command → Config loader: updates config · Adjusts persisted presentation and feature settings.
- Config loader → Config reader: reads from · Normalizes settings loaded from disk.
- Config reader → Claude config dir: resolves path · Finds the user Claude plugin config location.
- Stdin ingest → Telemetry: session state · Feeds live session metadata into derived metrics.
- Transcript parser → Telemetry: activity state · Provides tool, agent, and todo history.
- Telemetry → Git state: repo status · Augments session state with local git information.
- Telemetry → Memory probe: memory usage · Optionally reads host memory data.
- Telemetry → Version probe: version info · Optionally reads Claude Code installation version.
- Telemetry → Speed tracker: speed metric · Tracks token/output rate over time.
- Config loader → Renderer: render settings · Supplies layout, thresholds, and display toggles.
- Telemetry → Renderer: normalized state · Provides the current HUD snapshot for formatting.
- Renderer → Line builders: compose lines · Delegates to line-specific renderers.
- Line builders → Terminal utils: format output · Uses shared terminal helpers for width and styling.
- Source entry → Config loader: wires · Connects config loading into the runtime.
- Source entry → Stdin ingest: wires · Connects stdin ingestion into the runtime.
- Source entry → Renderer: wires · Connects rendering to stdout output.
- Source entry → Dist bundle: build output · Compiles TypeScript into the checked-in distribution artifact.
- Dist bundle → Claude Code: runtime plugin · Runs as the shipped statusline process inside Claude Code.