# jarrodwatts/claude-hud architecture

> Architecture diagram of the GitHub repository jarrodwatts/claude-hud, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jarrodwatts/claude-hud
- Repository: https://github.com/jarrodwatts/claude-hud

## Overview

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: [`src/config.ts`](https://github.com/jarrodwatts/claude-hud/blob/HEAD/src/config.ts) (Config loader), [`src/index.ts`](https://github.com/jarrodwatts/claude-hud/blob/HEAD/src/index.ts) (Source entry), [`src/render/index.ts`](https://github.com/jarrodwatts/claude-hud/blob/HEAD/src/render/index.ts) (Renderer), [`src/stdin.ts`](https://github.com/jarrodwatts/claude-hud/blob/HEAD/src/stdin.ts) (Stdin ingest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Plugin packaging"
  plugin_manifest["Plugin manifest<br/>plugin metadata<br/>[plugin.json]"]
  marketplace_manifest["Marketplace info<br/>distribution metadata<br/>[marketplace.json]"]
  setup_cmd["Setup command<br/>user command<br/>[setup.md]"]
  configure_cmd["Configure command<br/>user command<br/>[configure.md]"]
end

subgraph "Runtime core"
  config_loader["Config loader<br/>config normalization<br/>[config.ts]"]
  config_reader["Config reader<br/>config IO<br/>[config-reader.ts]"]
  claude_config_dir["Claude config dir<br/>path resolution"]
  stdin_ingest["Stdin ingest<br/>session input<br/>[stdin.ts]"]
  transcript_parser["Transcript parser<br/>event parser<br/>[transcript.ts]"]
  state_telemetry{{"Telemetry<br/>state derivation"}}
  speed_tracker["Speed tracker<br/>metric<br/>[speed-tracker.ts]"]
  renderer["Renderer<br/>statusline formatter<br/>[index.ts]"]
  line_builders["Line builders<br/>render components<br/>[index.ts]"]
  terminal_utils["Terminal utils<br/>formatting helpers<br/>[terminal.ts]"]
end

subgraph "Local dependencies"
  claude_code(("Claude Code<br/>host runtime"))
  git_state["Git state<br/>repo probe<br/>[git.ts]"]
  memory_probe["Memory probe<br/>host probe<br/>[memory.ts]"]
  version_probe["Version probe<br/>host probe<br/>[version.ts]"]
end

subgraph "Build and release"
  src_entry["Source entry<br/>package entry<br/>[index.ts]"]
  dist_bundle["Dist bundle<br/>published artifact<br/>[index.js]"]
end

claude_code -->|"status stream"| stdin_ingest
claude_code -->|"transcript events"| transcript_parser
claude_code -->|"loads plugin"| plugin_manifest
plugin_manifest -->|"publish metadata"| marketplace_manifest
setup_cmd -->|"writes config"| config_loader
configure_cmd -->|"updates config"| config_loader
config_loader -->|"reads from"| config_reader
config_reader -->|"resolves path"| claude_config_dir
stdin_ingest -->|"session state"| state_telemetry
transcript_parser -->|"activity state"| state_telemetry
state_telemetry -->|"repo status"| git_state
state_telemetry -->|"memory usage"| memory_probe
state_telemetry -->|"version info"| version_probe
state_telemetry -->|"speed metric"| speed_tracker
config_loader -->|"render settings"| renderer
state_telemetry -->|"normalized state"| renderer
renderer -->|"compose lines"| line_builders
line_builders -->|"format output"| terminal_utils
src_entry -->|"wires"| config_loader
src_entry -->|"wires"| stdin_ingest
src_entry -->|"wires"| renderer
src_entry -->|"build output"| dist_bundle
dist_bundle -->|"runtime plugin"| claude_code

click plugin_manifest "https://github.com/jarrodwatts/claude-hud/blob/main/.claude-plugin/plugin.json"
click marketplace_manifest "https://github.com/jarrodwatts/claude-hud/blob/main/.claude-plugin/marketplace.json"
click setup_cmd "https://github.com/jarrodwatts/claude-hud/blob/main/commands/setup.md"
click configure_cmd "https://github.com/jarrodwatts/claude-hud/blob/main/commands/configure.md"
click config_loader "https://github.com/jarrodwatts/claude-hud/blob/main/src/config.ts"
click config_reader "https://github.com/jarrodwatts/claude-hud/blob/main/src/config-reader.ts"
click claude_config_dir "https://github.com/jarrodwatts/claude-hud/blob/main/src/claude-config-dir.ts"
click stdin_ingest "https://github.com/jarrodwatts/claude-hud/blob/main/src/stdin.ts"
click transcript_parser "https://github.com/jarrodwatts/claude-hud/blob/main/src/transcript.ts"
click git_state "https://github.com/jarrodwatts/claude-hud/blob/main/src/git.ts"
click memory_probe "https://github.com/jarrodwatts/claude-hud/blob/main/src/memory.ts"
click version_probe "https://github.com/jarrodwatts/claude-hud/blob/main/src/version.ts"
click speed_tracker "https://github.com/jarrodwatts/claude-hud/blob/main/src/speed-tracker.ts"
click renderer "https://github.com/jarrodwatts/claude-hud/blob/main/src/render/index.ts"
click line_builders "https://github.com/jarrodwatts/claude-hud/blob/main/src/render/lines/index.ts"
click terminal_utils "https://github.com/jarrodwatts/claude-hud/blob/main/src/utils/terminal.ts"
click src_entry "https://github.com/jarrodwatts/claude-hud/blob/main/src/index.ts"
click dist_bundle "https://github.com/jarrodwatts/claude-hud/blob/main/dist/index.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class plugin_manifest,marketplace_manifest,setup_cmd,configure_cmd toneBlue
class config_loader,config_reader,claude_config_dir,stdin_ingest,transcript_parser,state_telemetry,speed_tracker,renderer,line_builders,terminal_utils toneAmber
class claude_code,git_state,memory_probe,version_probe toneMint
class src_entry,dist_bundle toneRose
```

## Components

### Plugin packaging

Discovery, install, and user commands for Claude Code.

- [Plugin manifest](https://github.com/jarrodwatts/claude-hud/blob/HEAD/.claude-plugin/plugin.json): plugin metadata · Claude Code plugin descriptor and marketplace entry. · `.claude-plugin/plugin.json`
- [Marketplace info](https://github.com/jarrodwatts/claude-hud/blob/HEAD/.claude-plugin/marketplace.json): distribution metadata · Marketplace registration and install metadata. · `.claude-plugin/marketplace.json`
- [Setup command](https://github.com/jarrodwatts/claude-hud/blob/HEAD/commands/setup.md): user command · Slash command that bootstraps Claude Code and HUD config. · `commands/setup.md`
- [Configure command](https://github.com/jarrodwatts/claude-hud/blob/HEAD/commands/configure.md): user command · Slash command for updating HUD settings. · `commands/configure.md`

### Runtime core

Live session ingestion, state synthesis, and statusline rendering.

- [Config loader](https://github.com/jarrodwatts/claude-hud/blob/HEAD/src/config.ts): config normalization · Loads defaults, validates settings, and resolves effective HUD configuration. · `src/config.ts`
- [Config reader](https://github.com/jarrodwatts/claude-hud/blob/HEAD/src/config-reader.ts): config IO · Reads persisted plugin configuration from the Claude config directory. · `src/config-reader.ts`
- [Claude config dir](https://github.com/jarrodwatts/claude-hud/blob/HEAD/src/claude-config-dir.ts): path resolution · Resolves the plugin configuration location under the user Claude directory. · `src/claude-config-dir.ts`
- [Stdin ingest](https://github.com/jarrodwatts/claude-hud/blob/HEAD/src/stdin.ts): session input · Parses structured status updates streamed from Claude Code on stdin. · `src/stdin.ts`
- [Transcript parser](https://github.com/jarrodwatts/claude-hud/blob/HEAD/src/transcript.ts): event parser · Parses transcript JSONL for tools, agents, and todo activity. · `src/transcript.ts`
- **Telemetry**: state derivation · Derives session metrics such as speed, memory, version, and git state.
- [Speed tracker](https://github.com/jarrodwatts/claude-hud/blob/HEAD/src/speed-tracker.ts): metric · Computes output speed over time from streaming activity. · `src/speed-tracker.ts`
- [Renderer](https://github.com/jarrodwatts/claude-hud/blob/HEAD/src/render/index.ts): statusline formatter · Coordinates line assembly and final terminal-safe output. · `src/render/index.ts`
- [Line builders](https://github.com/jarrodwatts/claude-hud/blob/HEAD/src/render/lines/index.ts): render components · Builds project, identity, environment, usage, memory, tools, agents, session, and todo lines. · `src/render/lines/index.ts`
- [Terminal utils](https://github.com/jarrodwatts/claude-hud/blob/HEAD/src/utils/terminal.ts): formatting helpers · 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**: host runtime · Launches the HUD, streams session state, and consumes the rendered statusline.
- [Git state](https://github.com/jarrodwatts/claude-hud/blob/HEAD/src/git.ts): repo probe · Reads branch and repository status from the local git checkout. · `src/git.ts`
- [Memory probe](https://github.com/jarrodwatts/claude-hud/blob/HEAD/src/memory.ts): host probe · Collects optional local memory usage information. · `src/memory.ts`
- [Version probe](https://github.com/jarrodwatts/claude-hud/blob/HEAD/src/version.ts): host probe · Reports installed Claude Code version when enabled. · `src/version.ts`

### Build and release

TypeScript source, checked-in dist artifact, and automation.

- [Source entry](https://github.com/jarrodwatts/claude-hud/blob/HEAD/src/index.ts): package entry · TypeScript entrypoint wiring the runtime together. · `src/index.ts`
- [Dist bundle](https://github.com/jarrodwatts/claude-hud/blob/HEAD/dist/index.js): published artifact · Checked-in compiled JavaScript used by the plugin runtime. · `dist/index.js`

## Connections

- 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.
