Claude HUD Autocompact Buffer Mode: Logic for Stable Layout Switching

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):

{
  "display": {
    "autocompactBuffer": "enabled"
  }
}

Disabled:

{
  "display": {
    "autocompactBuffer": "disabled"
  }
}

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

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

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.

Final Percentage Computation

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

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, lines 18-21):

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

Identity Line Rendering (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 (getBufferedPercent), consumed by src/render/session-line.ts and 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. 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 and src/render/lines/identity.ts.

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