# Claude HUD Autocompact Buffer Mode: Logic for Stable Layout Switching

> Discover the logic behind Claude HUD's autocompact buffer mode. Learn how it stabilizes layout switching by smoothing context-usage percentages and preventing jittery UI transitions.

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

---

**Claude HUD's autocompact buffer mode smooths context-usage percentages by applying a dynamically scaled buffer (up to ~16.5%) when usage falls between 5% and 50%, preventing jittery layout transitions caused by token count fluctuations near thresholds.**

The autocompact buffer mode in `jarrodwatts/claude-hud` eliminates flickering interface transitions by buffering raw token counts before displaying context usage percentages. This feature calculates dynamic padding that grows with session usage, ensuring the HUD maintains stable color zones and avoids oscillating between compact and expanded layouts when token counts hover near critical thresholds.

## How Autocompact Buffer Mode Works

Claude HUD supports two distinct layout modes for displaying session information:

- **Compact layout** – Renders model name, context bar, and project info on a single line optimized for quick scanning
- **Expanded layout** – Provides detailed multi-line output including separate sections for model, context, project, git status, and usage statistics

Both layouts rely on a **context-usage percentage** to determine visual styling and implicit layout switches. The autocompact buffer mode determines whether the HUD displays the raw token percentage or a buffered value that smooths transient fluctuations.

## Configuration and Usage

Control the buffering behavior through the `display.autocompactBuffer` configuration option.

**Enabled (Default):**

```json
{
  "display": {
    "autocompactBuffer": "enabled"
  }
}

```

**Disabled:**

```json
{
  "display": {
    "autocompactBuffer": "disabled"
  }
}

```

When disabled, the HUD emits a debug message to stderr revealing the comparison between values:

```bash
DEBUG=claude-hud node dist/index.js < input.json

```

Console output:

```

[claude-hud:context] autocompactBuffer=disabled, showing raw 30% (buffered would be 43%)

```

## Buffer Calculation Logic

The core buffering algorithm resides in [`src/stdin.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/stdin.ts) within the `getBufferedPercent` function (lines 64-89).

### Native Percentage Preference

For Claude Code v2.1.6 and later, the function first checks for an accurate `used_percentage` field reported by the Claude Code API. When present, this value returns unchanged, guaranteeing perfect synchronization with Claude Code's internal `/context` output.

### Linear Scaling Implementation

When native percentages are unavailable, the function implements a linear interpolation between 5% and 50% usage:

```typescript
const LOW = 0.05;               // 5%
const HIGH = 0.50;              // 50%
const scale = Math.min(1, Math.max(0, (rawRatio - LOW) / (HIGH - LOW)));
const buffer = size * AUTOCOMPACT_BUFFER_PERCENT * scale;

```

The constant `AUTOCOMPACT_BUFFER_PERCENT` (approximately 0.165 or 16.5%) is defined in [`src/constants.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/constants.ts).

### Final Percentage Computation

The calculated buffer gets added to the actual token count before percentage conversion:

```typescript
return Math.min(100,
    Math.round(((totalTokens + buffer) / size) * 100));

```

This inflation is strongest at 50% usage (full buffer applied) and tapers to zero below 5% usage, creating a smooth transition that prevents threshold bouncing.

## Rendering Pipeline Integration

Two render modules consume the buffered percentage to determine display output.

**Compact Line Rendering** ([`src/render/session-line.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/session-line.ts), lines 18-21):

```typescript
const autocompactMode = ctx.config?.display?.autocompactBuffer ?? 'enabled';
const percent = autocompactMode === 'disabled' ? rawPercent : bufferedPercent;

```

**Identity Line Rendering** ([`src/render/lines/identity.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/lines/identity.ts), lines 10-15):

This module implements identical logic for the expanded layout's context display line, ensuring consistent percentage representation across both view modes regardless of the `autocompactBuffer` setting.

## Why Buffering Matters for Layout Stability

The autocompact buffer mode addresses **boundary oscillation**—a UX problem where raw token counts fluctuating between 69% and 71% trigger rapid color changes (green to yellow) and potential layout expansions every few seconds.

By inflating the displayed percentage—particularly in the 5-50% range where usage commonly fluctuates—the buffer creates hysteresis that keeps color zones stable. This stability delays implicit switches to expanded layouts until the session genuinely approaches capacity thresholds, reducing visual noise during rapid development iterations.

## Summary

- **Configuration**: Set `display.autocompactBuffer` to `"enabled"` (default) for smoothed percentages or `"disabled"` for raw token counts
- **Calculation**: Uses linear interpolation between 5% and 50% usage to scale a buffer up to 16.5% of context window size
- **Implementation**: Core logic resides in [`src/stdin.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/stdin.ts) (`getBufferedPercent`), consumed by [`src/render/session-line.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/session-line.ts) and [`src/render/lines/identity.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/lines/identity.ts)
- **Behavior**: Adds calculated buffer to token count before percentage conversion, stabilizing display against minor fluctuations
- **Debugging**: Disable buffer mode to see exact raw percentages alongside buffered alternatives in debug output

## Frequently Asked Questions

### What is the default setting for autocompact buffer mode?

The default configuration sets `display.autocompactBuffer` to `"enabled"` as defined in [`src/config.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/config.ts). This ensures new installations immediately benefit from smoothed percentage displays without requiring manual configuration.

### How does the buffer percentage scale with context usage?

The buffer follows a linear ramp between 5% and 50% usage. Below 5% usage, no buffer applies; at 50% usage and above, the full 16.5% buffer applies. Between these values, the buffer scales proportionally using the formula `(rawRatio - 0.05) / 0.45`.

### Where can I see the difference between raw and buffered percentages?

Set the `autocompactBuffer` option to `"disabled"` and run Claude HUD with `DEBUG=claude-hud` enabled. The console outputs the raw percentage alongside what the buffered percentage would have been, formatted as `[claude-hud:context] autocompactBuffer=disabled, showing raw 30% (buffered would be 43%)`.

### Does disabling autocompact buffer mode affect performance?

No, disabling the buffer mode does not impact performance. The calculation overhead for the linear scaling is negligible. Disabling the mode simply changes which value—raw or buffered—gets passed to the rendering functions in [`src/render/session-line.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/session-line.ts) and [`src/render/lines/identity.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/lines/identity.ts).