# Claude HUD Compact vs Expanded Line Layouts: Rendering Pipeline Differences

> Explore Claude HUD's compact vs expanded rendering pipelines. Understand the differences in how each layout displays session data and context for efficient analysis.

- Repository: [Jarrod Watts/claude-hud](https://github.com/jarrodwatts/claude-hud)
- Tags: internals
- Published: 2026-03-18

---

**Claude HUD's compact layout renders a dense single session line with optional activity lines below, while the expanded layout displays each HUD element on separate lines with intelligent merging of adjacent context and usage metrics.**

Claude HUD, an open-source terminal interface developed by jarrodwatts/claude-hud, offers two distinct visual densities through its `lineLayout` configuration setting defined in [`src/config.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/config.ts). The choice between **compact** and **expanded** modes fundamentally alters the rendering pipeline in [`src/render/index.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/index.ts), determining whether status information compresses into a single line or distributes across multiple dedicated lines.

## How the Rendering Pipeline Diverges

The rendering pipeline splits early based on the `lineLayout` value. In [`src/render/index.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/index.ts), the main `render()` function checks `ctx.config?.lineLayout` and dispatches to either `renderCompact()` or `renderExpanded()`.

When `lineLayout === 'compact'`, the system invokes `renderCompact()` (lines 51-60), which returns an array containing only the session line. When `lineLayout === 'expanded'`, the system invokes `renderExpanded()` (lines 62-108), which builds an ordered list of individual element lines according to `config.elementOrder`.

### Compact Layout: The Single Session Line Approach

The **compact layout** prioritizes vertical space efficiency by condensing all primary HUD information into a single dense line. The `renderCompact()` function delegates to `renderSessionLine()` from [`src/render/session-line.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/session-line.ts) to generate this output, which includes the model identifier, context bar, project/git status, usage statistics, and duration.

Activity information—tools, agents, and todos—is excluded from the main session line. Instead, the system calls `collectActivityLines()` (lines 302-329) to gather these separately. If `showSeparators` is enabled, a dim-styled separator line is inserted between the session line and the activity lines.

### Expanded Layout: Multi-Line Element Rendering

The **expanded layout** dedicates individual lines to each HUD element according to the `elementOrder` configuration array, which defaults to `["project", "context", "usage", "environment", "tools", "agents", "todos"]`. The `renderExpanded()` function iterates through this array and calls `renderElementLine()` (lines 30-48) to dispatch to specialized renderers in `src/render/lines/`.

A key optimization occurs when `context` and `usage` appear consecutively in the order. The renderer merges these into a single combined line using the pattern `${firstLine} │ ${secondLine}`. Each element is flagged with `isActivity: boolean` (based on membership in `ACTIVITY_ELEMENTS`) to distinguish passive status lines from interactive activity indicators.

## Separator and Activity Line Handling Differences

The two layouts implement fundamentally different strategies for visual separation and activity display.

- **Compact mode**: Separators appear after the session line only when activity lines exist and `showSeparators` is true. The wrapping logic applies to the entire output block after assembly.
- **Expanded mode**: Separators are inserted once before the first activity line (tools, agents, or todos). Each element line is wrapped individually before concatenation into the final output, allowing for more granular text truncation decisions.

## Configuration and Implementation Examples

Users control these rendering paths through the `~/.claude/settings.json` configuration file.

### Configuring Compact Layout

Set `lineLayout` to `compact` for a dense display:

```json
{
  "lineLayout": "compact",
  "showSeparators": true,
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true
  }
}

```

This produces output where the session line contains model, context bar, project/git status, usage, and duration data, followed by a separator and individual activity lines.

### Configuring Expanded Layout

Set `lineLayout` to `expanded` for detailed multi-line output:

```json
{
  "lineLayout": "expanded",
  "showSeparators": true,
  "elementOrder": ["project", "context", "usage", "environment", "tools", "agents", "todos"]
}

```

This configuration renders each element on its own line, with context and usage potentially combined if they appear consecutively, and separators inserted before the first activity element.

### Programmatic Rendering

Developers can invoke the renderer directly in Node.js:

```javascript
import { render } from './dist/index.js';
import { loadConfig } from './dist/config-reader.js';
import { parseStdin } from './dist/stdin.js';

const stdin = parseStdin(process.stdin);
const cfg = await loadConfig();
const ctx = { stdin, config: cfg };

render(ctx);

```

Switching `cfg.lineLayout` between `'compact'` and `'expanded'` automatically toggles the rendering path between `renderCompact()` and `renderExpanded()`.

## Core Source Files and Functions

Understanding the implementation requires familiarity with these specific modules:

- **[`src/render/index.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/index.ts)**: Contains the main `render()` dispatcher, `renderCompact()` (lines 51-60), `renderExpanded()` (lines 62-108), and `collectActivityLines()` (lines 302-329).
- **[`src/render/session-line.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/session-line.ts)**: Implements `renderSessionLine()` for generating the compact mode's dense status summary.
- **[`src/render/lines/project.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/lines/project.ts)**: Renders project path and git status for expanded mode.
- **[`src/render/lines/identity.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/lines/identity.ts)**: Generates the context bar line (`[model]` + progress bar) used in expanded layouts.
- **[`src/render/lines/usage.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/lines/usage.ts)**: Handles usage statistics display for expanded mode.
- **[`src/render/lines/environment.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/lines/environment.ts)**: Renders configuration counts (CLAUDE.md, rules, MCPs).
- **[`src/config.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/config.ts)**: Defines the `lineLayout` type union and default configuration values.

## Summary

- **Compact mode** uses `renderCompact()` to generate a single dense session line via `renderSessionLine()`, with activity lines collected separately by `collectActivityLines()`.
- **Expanded mode** uses `renderExpanded()` to iterate through `elementOrder`, rendering each HUD element on its own line and merging adjacent context/usage pairs when they appear consecutively.
- Separators in compact mode appear after the session line; in expanded mode, they appear before the first activity line flagged by `isActivity`.
- The `lineLayout` configuration property in [`src/config.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/config.ts) controls which rendering path executes in [`src/render/index.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/index.ts).
- Both modes support activity lines (tools, agents, todos) but handle their collection and display through different architectural patterns.

## Frequently Asked Questions

### What configuration setting controls the layout mode in Claude HUD?

The `lineLayout` property in your `~/.claude/settings.json` file controls the rendering approach. Set it to `'compact'` for a single-line session summary or `'expanded'` for multi-line element display. This value is read from `ctx.config` in [`src/render/index.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/index.ts) and defaults to `'expanded'` if not specified.

### How does Claude HUD handle context and usage display differently between layouts?

In compact mode, context and usage are embedded within the single session line generated by `renderSessionLine()`. In expanded mode, these typically render on separate lines, but `renderExpanded()` optimizes by merging them into one line when they appear consecutively in `elementOrder`, joining them with a `│` separator to reduce vertical sprawl.

### Where are activity lines (tools, agents, todos) rendered in each layout?

Compact mode collects activity lines via `collectActivityLines()` in [`src/render/index.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/index.ts) (lines 302-329) and appends them after an optional separator. Expanded mode marks activity elements with `isActivity: true` during iteration and renders them as individual lines within the main element order, inserting a separator before the first activity occurrence when `showSeparators` is enabled.

### Can I customize which elements appear in the expanded layout?

Yes. The `elementOrder` array in your configuration determines which HUD elements render and in what sequence. The default order is `["project", "context", "usage", "environment", "tools", "agents", "todos"]`, but you can reorder or omit elements as needed. The `renderExpanded()` function respects this array when building output lines in [`src/render/index.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/index.ts).