Claude HUD Context Bar Color Thresholds: Green, Yellow, and Red Levels Explained

Claude HUD uses three hard-coded percentage thresholds to color-code context window usage: green below 70%, yellow from 70% to 84%, and red at 85% and above.

The Claude HUD project, available in the jarrodwatts/claude-hud repository, provides a terminal-based heads-up display for monitoring Claude's context window consumption. The context bar serves as the primary visual indicator of token usage, shifting colors to warn users as they approach the model's limits.

Understanding the Three Color Thresholds

The color logic follows a simple tiered system defined in the source code:

• Green (< 70%): Indicates normal, safe usage levels with plenty of context window remaining.
• Yellow (70% – 84%): Signals a warning zone where users should consider summarizing or clearing context soon.
• Red (≥ 85%): Represents critical levels where the context window is nearly exhausted and imminent truncation is likely.

These thresholds are intentionally conservative to provide early warning before hitting the absolute limit.

How the Color Logic Is Implemented in Code

The getContextColor Function in colors.ts

The core logic resides in src/render/colors.ts within the getContextColor function. This utility accepts a percentage value and returns the appropriate ANSI color code:

export function getContextColor(percent: number, colors?: Partial<HudColorOverrides>): string {
  if (percent >= 85) return resolveAnsi(colors?.critical, RED);   // red
  if (percent >= 70) return resolveAnsi(colors?.warning, YELLOW); // yellow
  return resolveAnsi(colors?.context, GREEN);                     // green
}

The function checks thresholds in descending order (85%, then 70%) and defaults to green if neither threshold is met. It also supports optional color overrides through the HudColorOverrides interface, though the threshold percentages themselves remain fixed.

Where the Colors Are Applied in the UI

Rendering the Numeric Percentage in identity.ts

The color returned by getContextColor is applied to the percentage display in src/render/lines/identity.ts. The renderIdentityLine function wraps the numeric value with the appropriate ANSI color:

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

This ensures the percentage number (e.g., "76%") appears in yellow when the context usage falls within the warning threshold.

Rendering the Bar Graphic

The same color logic drives the visual bar graphic through the coloredBar helper function, also defined in src/render/colors.ts. This function constructs the bar using block characters:

return `${color}${'█'.repeat(filled)}${DIM}${'░'.repeat(empty)}${RESET}`;

Internally, coloredBar calls getContextColor(percent) to determine the color for the filled portion of the bar. The result is a cohesive visual indicator where both the bar segments and the percentage number share the same color based on the current usage level.

Practical Code Examples

Using coloredBar Directly

You can import and use the coloredBar function to generate color-coded progress bars for any percentage value:

import { coloredBar } from './render/colors.js';

// 45% usage - green bar
console.log(coloredBar(45, 10));
// Output: ████░░░░░░ (in green)

// 78% usage - yellow bar  
console.log(coloredBar(78, 10));
// Output: ███████░░░ (in yellow)

// 92% usage - red bar
console.log(coloredBar(92, 10));
// Output: ██████████ (in red)

Rendering Full Identity Lines

To see the complete context line with both the bar and percentage colored according to the thresholds:

import { renderIdentityLine } from './render/lines/identity.js';

// Mock context with 65% usage (green)
const greenContext = { /* ... */ };
console.log(renderIdentityLine(greenContext));

// Mock context with 73% usage (yellow)  
const yellowContext = { /* ... */ };
console.log(renderIdentityLine(yellowContext));

// Mock context with 88% usage (red)
const redContext = { /* ... */ };
console.log(renderIdentityLine(redContext));

Each call outputs a formatted line like Context [bar] 73% with the appropriate color coding applied to both visual elements.

Summary

• Claude HUD implements three fixed color thresholds for context window visualization: green below 70%, yellow from 70% to 84%, and red at 85% and above.
• The logic is centralized in src/render/colors.ts within the getContextColor function, which returns ANSI color codes based on percentage checks.
• Colors are applied consistently across both the numeric percentage display in src/render/lines/identity.ts and the visual bar graphic via the coloredBar helper.
• These thresholds provide early visual warning before context window exhaustion, with the conservative 85% red threshold ensuring users have time to take corrective action.

Frequently Asked Questions

What are the exact percentage thresholds for Claude HUD's context bar?

Claude HUD uses three specific thresholds: green displays when usage is below 70%, yellow displays between 70% and 84%, and red displays at 85% and above. These values are hard-coded in the getContextColor function within src/render/colors.ts and are not configurable through standard settings.

Can I customize the color thresholds in Claude HUD?

While the percentage thresholds themselves are fixed at 70% and 85%, the colors associated with each threshold can be customized through the HudColorOverrides interface. The getContextColor function accepts an optional colors parameter that allows you to override the default green, yellow, and red ANSI color codes, though the logic determining when each color appears remains unchanged.

Which source file contains the color logic for the context bar?

The core color threshold logic resides in src/render/colors.ts, specifically within the getContextColor function at lines 67-71. This file also contains the coloredBar helper function that applies these colors to the visual bar graphic. The actual rendering of the context line occurs in src/render/lines/identity.ts, which imports and calls the color functions from colors.ts.

How does Claude HUD calculate the percentage for the context bar?

The percentage value passed to getContextColor is derived from the ratio of input_tokens to the total context_window size provided in the stdin context data. While the raw analysis focuses on the color application rather than the calculation logic, the percentage is computed upstream in the rendering pipeline before being passed to renderIdentityLine and subsequently to getContextColor for color determination.

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