Configuration #

Claude HUD is highly customizable. You can adjust the layout, choose which elements to display, change colors, control thresholds, and reorder sections — all through a single JSON config file.

Prerequisites: Getting Started (Claude HUD installed and running)

Configuration Methods #

There are two ways to configure Claude HUD:

Interactive Setup #

Run the built-in configuration command inside Claude Code:

/claude-hud:configure

This guided flow lets you pick a preset, toggle individual elements, and preview the result before saving. Any manual edits you have made (such as custom colors or thresholds) are preserved.

Manual Editing #

Edit the config file directly for full control over every option:

~/.claude/plugins/claude-hud/config.json

The file uses standard JSON. If the file does not exist, Claude HUD uses its built-in defaults. If the file contains invalid JSON, it silently falls back to defaults as well.

Presets #

When you run /claude-hud:configure, you start by choosing a preset. Each preset is a starting point — you can customize individual settings afterward.

After selecting a preset, the interactive flow walks you through toggling individual elements on or off.

Layout Options #

Line Layout #

The lineLayout option controls how HUD information is arranged:

{
  "lineLayout": "expanded"
}

Separators #

Add visual separators between elements in the display:

{
  "showSeparators": true
}

When enabled, elements are divided by | characters for visual clarity.

Project Path Depth #

Control how many directory levels appear in the project path display:

{
  "pathLevels": 2
}

Only values 1, 2, or 3 are accepted. Any other value falls back to the default of 1.

Element Order #

In expanded layout mode, you can control the order of HUD elements and hide elements by omitting them:

{
  "elementOrder": ["project", "tools", "context", "usage", "environment", "agents", "todos"]
}

Available elements: project, context, usage, environment, tools, agents, todos.

Elements not included in the array are hidden in expanded mode. Duplicate entries and unrecognized names are ignored.

Display Toggles #

The display object controls the visibility and behavior of individual HUD components.

Session Information #

Context Display #

The contextValue option accepts three formats:

Usage Limits #

Usage display is available for Claude Pro, Max, and Team subscribers. API users do not have rate limits and will not see usage data.

When the 7-day usage exceeds the configured threshold, an additional bar appears:

Context ████░░░░░░ 45% | Usage ██░░░░░░░░ 25% (1h 30m / 5h) | ██████████ 85% (2d / 7d)

Activity Lines #

These lines are hidden by default and only appear when there is activity to display.

Enable all three for maximum visibility:

{
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true
  }
}

Autocompact Buffer #

When enabled, the HUD displays a warning when context is approaching the autocompact threshold. Set to "disabled" to hide this indicator.

Git Status #

The gitStatus section controls how repository information appears in the HUD.

{
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": true
  }
}

With all options enabled, the display looks like:

[Opus] | my-project git:(main* up2 down1 !3 +1 ?2)

File stat indicators:

Counts of zero are omitted for a cleaner display.

Colors #

Customize the color scheme with the colors object. Colors apply to progress bars, percentages, and warning states.

{
  "colors": {
    "context": "cyan",
    "usage": "cyan",
    "warning": "yellow",
    "usageWarning": "magenta",
    "critical": "red"
  }
}

Available Color Names #

red, green, yellow, magenta, cyan, brightBlue, brightMagenta

Invalid color names fall back to the default for that key.

Usage Cache #

The usage section controls how often Claude HUD refreshes rate limit data from the Anthropic API.

{
  "usage": {
    "cacheTtlSeconds": 120,
    "failureCacheTtlSeconds": 30
  }
}

Both values must be positive integers. Invalid values fall back to their defaults.

Increasing cacheTtlSeconds reduces API calls but makes usage data less current. In high-latency environments, you can also set the CLAUDE_HUD_USAGE_TIMEOUT_MS environment variable (in milliseconds) to increase the API request timeout.

Full Example #

Here is a complete configuration that enables all features with customized colors:

{
  "lineLayout": "expanded",
  "showSeparators": false,
  "pathLevels": 2,
  "elementOrder": ["project", "tools", "context", "usage", "environment", "agents", "todos"],
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": true
  },
  "display": {
    "showModel": true,
    "showProject": true,
    "showContextBar": true,
    "contextValue": "percent",
    "showConfigCounts": true,
    "showDuration": true,
    "showSpeed": false,
    "showTokenBreakdown": true,
    "showUsage": true,
    "usageBarEnabled": true,
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showSessionName": false,
    "autocompactBuffer": "enabled",
    "usageThreshold": 0,
    "sevenDayThreshold": 80,
    "environmentThreshold": 0
  },
  "usage": {
    "cacheTtlSeconds": 60,
    "failureCacheTtlSeconds": 15
  },
  "colors": {
    "context": "cyan",
    "usage": "brightBlue",
    "warning": "yellow",
    "usageWarning": "magenta",
    "critical": "red"
  }
}

Validation and Defaults #

Claude HUD validates every config value on load. Invalid values silently fall back to their defaults — the HUD never crashes due to a bad config.

Legacy Config Migration #

If you have a config file from an older version of Claude HUD (v0.0.x), the layout field is automatically migrated:

• "layout": "separators" becomes lineLayout: "compact" with showSeparators: true
• "layout": "default" becomes lineLayout: "compact" with showSeparators: false

No manual migration is needed.

Related Topics #

• HUD Elements — Detailed guide to every indicator in the display
• Troubleshooting — Fixing config-related issues
• Overview — What Claude HUD is and why it matters