When Does Claude HUD Show the Token Breakdown Display at 85% Context Usage?

Claude HUD appends the detailed token breakdown "(in: X, cache: Y)" to the status line only when the showTokenBreakdown configuration is enabled (defaulting to true) and the computed context usage percentage reaches 85% or higher.

The Claude HUD project (jarrodwatts/claude-hud) provides real-time visibility into Claude Code sessions, automatically surfacing granular token metrics when you approach critical context limits. Understanding the precise trigger conditions for this display helps developers monitor expensive, long-running conversations before hitting the context window wall.

The Dual Conditions for Triggering the Token Breakdown

The token breakdown display is governed by a strict logical AND operation evaluated during every render cycle. Both conditions must be satisfied simultaneously for the suffix to appear.

Configuration Flag: showTokenBreakdown

The primary gate is the showTokenBreakdown setting defined in src/config.ts. This boolean defaults to true, meaning the breakdown is enabled by default unless explicitly disabled. The renderer checks this flag using a loose inequality guard:

if (display?.showTokenBreakdown !== false && percent >= 85) {
  // ... append token breakdown
}

If you set showTokenBreakdown to false in your configuration file, the breakdown is suppressed regardless of how high context usage climbs.

The 85% Context Usage Threshold

The second condition evaluates the current context consumption percentage. The HUD calculates this value differently based on the autocompactBuffer setting:

• Raw percent: Computed via getContextPercent(ctx.stdin) (actual tokens used divided by total context window size)
• Buffered percent: Computed via getBufferedPercent(ctx.stdin) when autocompactBuffer is 'enabled' (default), adding a safety buffer to the calculation

In both cases, the threshold is hardcoded at 85. The check appears in both src/render/session-line.ts (around lines 210-218) and src/render/lines/identity.ts (lines 27-34), ensuring consistent behavior across the compact identity line and the full session output.

How the Token Data Is Extracted and Formatted

When both conditions pass, the HUD reads current usage statistics from the stdin JSON payload and formats them into a dimmed parenthetical suffix.

The extraction logic accesses the nested context window data:

const usage = ctx.stdin.context_window?.current_usage;
if (usage) {
  const input = formatTokens(usage.input_tokens ?? 0);
  const cache = formatTokens(
    (usage.cache_creation_input_tokens ?? 0) + 
    (usage.cache_read_input_tokens ?? 0)
  );
  line += dim(` (in: ${input}, cache: ${cache})`);
}

The formatTokens() utility converts raw integers (e.g., 180000) into human-readable shorthand (e.g., "180k"). Cache totals aggregate both creation and read tokens, giving you a complete picture of cached versus live input costs.

Source Code Implementation Details

The trigger logic is split across three critical files in the repository:

File	Purpose	Specific Location
src/config.ts	Defines the showTokenBreakdown boolean and its default value (true)	Default configuration object
src/render/lines/identity.ts	Renders the compact "Context" bar on the first line	Lines 27-34 contain the dual condition check
src/render/session-line.ts	Assembles the full multi-line status output	Lines 210-218 handle the token breakdown block

Both rendering paths evaluate the identical condition: if (display?.showTokenBreakdown !== false && percent >= 85). This redundancy ensures that whether you're viewing the compact identity line or the detailed session view, the breakdown appears consistently once you cross the 85% threshold.

Configuration and Customization Examples

Default High-Context Scenario

With default settings enabled, feeding the HUD a stdin payload showing 87% usage triggers the automatic display:

{
  "model": { "display_name": "Opus" },
  "context_window": {
    "current_usage": {
      "input_tokens": 180000,
      "cache_creation_input_tokens": 20000,
      "cache_read_input_tokens": 5000
    },
    "context_window_size": 200000
  }
}

This yields a status line resembling:

[Opus] │ my-project git:(main*) │ Context █████░░░░░ 87% (in: 180k, cache: 25k)

The (in: 180k, cache: 25k) suffix appears because percent (87) is greater than or equal to 85.

Disabling the Breakdown Display

To suppress the token details even at high usage, modify your HUD configuration file (typically ~/.claude/settings.json):

{
  "display": {
    "showTokenBreakdown": false
  }
}

With the same 87% usage payload, the output now omits the breakdown:

[Opus] │ my-project git:(main*) │ Context █████░░░░░ 87%

Customizing the Hardcoded Threshold

The 85% threshold is currently hardcoded in the source. To trigger the breakdown at a lower percentage (e.g., 80%), modify the condition in either src/render/session-line.ts or src/render/lines/identity.ts:

// Change from:
if (display?.showTokenBreakdown !== false && percent >= 85) {

// To:
if (display?.showTokenBreakdown !== false && percent >= 80) {

After modifying the source, rebuild the project with npm run build. The token breakdown will now appear whenever usage hits 80% or higher.

Summary

• Dual trigger logic: The token breakdown requires both display?.showTokenBreakdown !== false (default true) and percent >= 85.
• Source locations: The check is implemented in src/render/session-line.ts (lines 210-218) and src/render/lines/identity.ts (lines 27-34).
• Percentage calculation: Uses either raw context percent or buffered percent depending on the autocompactBuffer setting.
• Data source: Reads from ctx.stdin.context_window?.current_usage, formatting input_tokens and combined cache tokens into a dimmed suffix.
• No config threshold: The 85% limit is hardcoded; changing it requires editing the source TypeScript files.

Frequently Asked Questions

What configuration controls the token breakdown display in Claude HUD?

The showTokenBreakdown boolean in the HUD display configuration controls this feature. Located in src/config.ts, it defaults to true, meaning the breakdown is enabled by default. Set it to false in your settings JSON to disable the feature entirely.

At what percentage does Claude HUD trigger the token breakdown?

The breakdown triggers when context usage reaches 85% or higher. This threshold is hardcoded in the source and evaluated against either the raw context percentage or the buffered percentage (if autocompact is enabled) depending on your configuration.

Can I change the 85% threshold for the token breakdown display?

No, the threshold is not exposed as a configuration option. It is hardcoded as percent >= 85 in both src/render/session-line.ts and src/render/lines/identity.ts. To use a different threshold, you must manually edit the source code and rebuild the project.

Which source files handle the token breakdown rendering logic?

The logic is split between two rendering modules. src/render/lines/identity.ts (lines 27-34) handles the compact single-line "Context" bar, while src/render/session-line.ts (lines 210-218) handles the detailed multi-line session output. Both files contain identical conditional checks for the 85% threshold and the showTokenBreakdown flag.

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