Claude HUD Compact vs Expanded Line Layouts: Rendering Pipeline Differences

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. The choice between compact and expanded modes fundamentally alters the rendering pipeline in 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, 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 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:

{
  "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:

{
  "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:

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: Contains the main render() dispatcher, renderCompact() (lines 51-60), renderExpanded() (lines 62-108), and collectActivityLines() (lines 302-329).
• src/render/session-line.ts: Implements renderSessionLine() for generating the compact mode's dense status summary.
• src/render/lines/project.ts: Renders project path and git status for expanded mode.
• src/render/lines/identity.ts: Generates the context bar line ([model] + progress bar) used in expanded layouts.
• src/render/lines/usage.ts: Handles usage statistics display for expanded mode.
• src/render/lines/environment.ts: Renders configuration counts (CLAUDE.md, rules, MCPs).
• 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 controls which rendering path executes in 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 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 (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}