Claude HUD Context Value Display Modes: Percent, Tokens, and Remaining Explained

Claude HUD provides three context value display modes—percent, tokens, and remaining—controlled via the display.contextValue setting in ~/.claude/settings.json, each calculating usage differently based on raw or buffered percentages and total token counts.

The Claude HUD project by jarrodwatts/claude-hud renders a real-time heads-up display for Claude Code sessions, including a Context line that shows exactly how much of the available context window is being consumed. Understanding these context value display modes helps developers monitor token usage accurately, whether they prefer percentage-based metrics, absolute token counts, or remaining capacity indicators.

The Three Context Value Display Modes

The HUD determines which value to render by reading the display.contextValue configuration option. When unspecified, it defaults to percent.

Percent Mode (Default)

In percent mode, the HUD displays the current context usage as a percentage value, such as 45%. According to the source code in src/render/lines/identity.ts, this mode calls formatContextValue with the mode parameter set to percent, passing either the raw native percentage or a buffered percentage depending on autocompact settings.

The percentage calculation originates from getContextPercent or getBufferedPercent functions defined in src/stdin.ts. When displayed, the value appears alongside a progress bar:

Context ████░░░░░░ 45%

Tokens Mode

Setting contextValue to tokens switches the display to show absolute token consumption relative to the context window size, formatted as total/size (e.g., 45k/200k).

In src/render/lines/identity.ts, the formatContextValue function handles this by invoking getTotalTokens, which sums input_tokens, cache_creation_input_tokens, and cache_read_input_tokens. If the context window size is known, it formats the ratio; otherwise, it displays only the total. Large numbers are abbreviated using k for thousands and M for millions.

Remaining Mode

The remaining mode shows the inverse of percentage usage—how much capacity is left in the context window. The calculation occurs in formatContextValue at lines 59-61 of src/render/lines/identity.ts, where it computes 100 - percent and clamps the result to a minimum of 0.

For example, if the current usage is 45%, the display renders 55%, indicating the remaining headroom before hitting the context limit.

How Context Calculation Works

Raw vs. Buffered Percentage

The percent and remaining modes rely on a base percentage value that varies based on the autocompact buffer configuration. In src/render/lines/identity.ts, the logic distinguishes between:

• Raw percent: The native usage percentage retrieved via getContextPercent(ctx.stdin)
• Buffered percent: The raw percentage plus the autocompact safety margin retrieved via getBufferedPercent(ctx.stdin)

The autocompactBuffer setting in display configuration determines which value applies:

const rawPercent = getContextPercent(ctx.stdin);
const bufferedPercent = getBufferedPercent(ctx.stdin);
const autocompactMode = ctx.config?.display?.autocompactBuffer ?? 'enabled';
const percent = autocompactMode === 'disabled' ? rawPercent : bufferedPercent;

When display.autocompactBuffer is set to disabled, the HUD shows the raw usage percentage without the safety buffer. When enabled (default), it uses the buffered percentage defined by AUTOCOMPACT_BUFFER_PERCENT in src/constants.ts, which adds a margin mirroring Claude Code's internal autocompact behavior.

Configuration and Usage Examples

Configure your preferred mode by editing ~/.claude/settings.json:

Example 1: Default Percent Mode

{
  "display": {
    "contextValue": "percent"
  }
}

Output:

Context ████░░░░░░ 45%

Example 2: Absolute Token Counts

{
  "display": {
    "contextValue": "tokens"
  }
}

Output:

Context ████░░░░░░ 45k/200k

Example 3: Remaining Capacity

{
  "display": {
    "contextValue": "remaining"
  }
}

Output:

Context ████░░░░░░ 55%

Example 4: Disabling Autocompact Buffer

{
  "display": {
    "contextValue": "percent",
    "autocompactBuffer": "disabled"
  }
}

Output:

Context ████░░░░░░ 42%

Visual Feedback and Color Coding

Regardless of the selected mode, Claude HUD applies consistent color coding to the context value based on usage thresholds. The getContextColor function assigns:

• Green: Usage below 70%
• Yellow: Usage between 70% and 85%
• Red: Usage above 85%

The color is applied in src/render/lines/identity.ts after formatting:

const contextValueDisplay = `${getContextColor(percent, colors)}${contextValue}${RESET}`;

This visual feedback operates on the underlying percentage value (raw or buffered), ensuring that the color accurately reflects proximity to the context limit even when displaying tokens or remaining percentages.

Summary

• Three display modes control the Context line: percent (default), tokens, and remaining, configured via display.contextValue in ~/.claude/settings.json.
• Percent mode shows current usage as a percentage, calculated by getContextPercent or getBufferedPercent and formatted by formatContextValue in src/render/lines/identity.ts.
• Tokens mode displays absolute consumption (e.g., 45k/200k) using getTotalTokens to aggregate input and cache tokens from src/stdin.ts.
• Remaining mode inverts the percentage to show available context headroom, calculated as 100 - percent with a minimum floor of 0.
• Autocompact buffering affects percent calculations: when enabled (default), it adds the buffer margin defined in src/constants.ts; when disabled, it uses raw percentages.
• Color coding (green/yellow/red) applies universally based on the underlying percentage threshold, implemented via getContextColor.

Frequently Asked Questions

How do I change the context display mode in Claude HUD?

Modify the display.contextValue setting in your ~/.claude/settings.json file to one of three string values: "percent", "tokens", or "remaining". If omitted, the system defaults to "percent". Restart or reload Claude HUD to apply the configuration change.

What is the difference between percent and remaining modes?

Percent mode displays the consumed portion of the context window (e.g., 45%), while remaining mode displays the available capacity (e.g., 55%). Both modes calculate from the same underlying percentage value—either raw or buffered depending on autocompact settings—but present inverse metrics to suit different monitoring preferences.

How does the autocompact buffer affect context calculation?

When display.autocompactBuffer is enabled (default), the HUD adds a safety margin percentage—defined as AUTOCOMPACT_BUFFER_PERCENT in src/constants.ts—to the raw usage percentage via getBufferedPercent. This buffered value is used for percent and remaining calculations, providing conservative estimates that align with Claude Code's autocompact behavior. Disabling the buffer uses the raw percentage from getContextPercent without modification.

Where does Claude HUD get the token count data?

Token counts originate from the stdin context object processed in src/stdin.ts. The getTotalTokens function aggregates three token types: input_tokens, cache_creation_input_tokens, and cache_read_input_tokens. This data feeds into formatContextValue in src/render/lines/identity.ts to generate the absolute token displays used in tokens mode.

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