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

> Understand Claude HUD context display modes percent, tokens, and remaining. Learn how each mode calculates usage in your settings.json file for better Claude token management.

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

---

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

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

```json
{
  "display": {
    "contextValue": "percent"
  }
}

```

Output:

```

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

```

**Example 2: Absolute Token Counts**

```json
{
  "display": {
    "contextValue": "tokens"
  }
}

```

Output:

```

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

```

**Example 3: Remaining Capacity**

```json
{
  "display": {
    "contextValue": "remaining"
  }
}

```

Output:

```

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

```

**Example 4: Disabling Autocompact Buffer**

```json
{
  "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`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/lines/identity.ts) after formatting:

```typescript
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`](https://github.com/jarrodwatts/claude-hud/blob/main/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`](https://github.com/jarrodwatts/claude-hud/blob/main/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`](https://github.com/jarrodwatts/claude-hud/blob/main/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`](https://github.com/jarrodwatts/claude-hud/blob/main/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`](https://github.com/jarrodwatts/claude-hud/blob/main/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`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/lines/identity.ts) to generate the absolute token displays used in tokens mode.