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

> Discover when Claude HUD displays the token breakdown at 85% context usage. Learn how to configure this helpful feature for tracking token counts.

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

---

**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`](https://github.com/jarrodwatts/claude-hud/blob/main/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:

```typescript
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`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/session-line.ts) (around lines 210-218) and [`src/render/lines/identity.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/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:

```typescript
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`](https://github.com/jarrodwatts/claude-hud/blob/main/src/config.ts) | Defines the `showTokenBreakdown` boolean and its default value (`true`) | Default configuration object |
| [`src/render/lines/identity.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/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`](https://github.com/jarrodwatts/claude-hud/blob/main/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:

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

```text
[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`):

```json
{
  "display": {
    "showTokenBreakdown": false
  }
}

```

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

```text
[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`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/session-line.ts) or [`src/render/lines/identity.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/lines/identity.ts):

```typescript
// 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`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/session-line.ts) (lines 210-218) and [`src/render/lines/identity.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/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`](https://github.com/jarrodwatts/claude-hud/blob/main/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`](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). 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`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/lines/identity.ts) (lines 27-34) handles the compact single-line "Context" bar, while [`src/render/session-line.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/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.