Skip to main content
Claude HUD stores its configuration in a single JSON file. You can configure it interactively using the built-in command, or edit the file directly for advanced settings.

​
Config file location

~/.claude/plugins/claude-hud/config.json
If this file does not exist, Claude HUD uses its built-in defaults. Invalid JSON silently falls back to defaults as well.

​
Interactive configuration

Run the configure command from any Claude Code session: 
/claude-hud:configure
The guided flow lets you:
  • Choose a preset as a starting point (Full, Essential, or Minimal)
  • Toggle individual display elements on or off
  • Set your git status display style
  • Switch between expanded and compact layouts
  • Add a custom phrase to your HUD
  • Preview exactly how your HUD will look before saving
Advanced settings such as colors.*, pathLevels, display.usageThreshold, and display.environmentThreshold are preserved when you run /claude-hud:configure — the interactive flow does not overwrite them.

​
Manual editing

Edit ~/.claude/plugins/claude-hud/config.json directly for settings that the interactive flow does not expose. Changes take effect immediately — no restart required. 
# Open with your editor of choice
nano ~/.claude/plugins/claude-hud/config.json

​
Full configuration schema

Every field and its default value:
FieldTypeDefaultDescription
lineLayoutexpanded | compactexpandedMulti-line or single-line layout
showSeparatorsbooleanfalseShow separator before activity lines in compact mode
pathLevels1 | 2 | 31Directory depth for project path display
elementOrderstring[]see belowRender order of expanded-mode elements
gitStatus.enabledbooleantrueShow git branch
gitStatus.showDirtybooleantrueShow * for uncommitted changes
gitStatus.showAheadBehindbooleanfalseShow ↑N ↓N ahead/behind remote
gitStatus.showFileStatsbooleanfalseShow !M +A ✘D ?U file change counts
display.showModelbooleantrueShow model name [Opus]
display.showProjectbooleantrueShow project path
display.showContextBarbooleantrueShow visual context bar
display.contextValuepercent | tokens | remainingpercentContext display format
display.showConfigCountsbooleanfalseShow CLAUDE.md, rules, MCPs, hooks counts
display.showDurationbooleanfalseShow session duration
display.showSpeedbooleanfalseShow output token speed
display.showTokenBreakdownbooleantrueShow token details at high context
display.showUsagebooleantrueShow usage limits (Pro/Max/Team)
display.usageBarEnabledbooleantrueVisual bar vs text for usage
display.showToolsbooleanfalseShow tools activity line
display.showAgentsbooleanfalseShow agents activity line
display.showTodosbooleanfalseShow todos progress line
display.showSessionNamebooleanfalseShow session name or custom title
display.autocompactBufferenabled | disabledenabledAutocompact buffer behavior
display.usageThresholdnumber0Minimum usage % before showing usage bar
display.sevenDayThresholdnumber80Show 7-day bar when 7-day usage >= this %
display.environmentThresholdnumber0Minimum % before showing environment line
display.customLinestring''Custom phrase shown in the HUD (max 80 chars)
usage.cacheTtlSecondsnumber60Seconds to cache a successful usage API response
usage.failureCacheTtlSecondsnumber15Seconds to cache a failed usage API response
colors.contextcolorgreenColor for context bar and percentage
colors.usagecolorbrightBlueColor for usage bar below warning threshold
colors.warningcoloryellowWarning color for context and usage text
colors.usageWarningcolorbrightMagentaColor for usage near threshold
colors.criticalcolorredColor for limit-reached and critical states
The default elementOrder is: 
["project", "context", "usage", "environment", "tools", "agents", "todos"]

​
Example configuration

{
  "lineLayout": "expanded",
  "pathLevels": 2,
  "elementOrder": ["project", "tools", "context", "usage", "environment", "agents", "todos"],
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": true
  },
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showConfigCounts": true,
    "showDuration": true
  },
  "colors": {
    "context": "cyan",
    "usage": "cyan",
    "warning": "yellow",
    "usageWarning": "magenta",
    "critical": "red"
  },
  "usage": {
    "cacheTtlSeconds": 120,
    "failureCacheTtlSeconds": 30
  }
}

​
Configuration pages

Presets

Start with Full, Essential, or Minimal and fine-tune from there.

Display options

Toggle every individual display element and set layout options.

Git status

Control how git branch, dirty state, and file stats appear.

Colors

Customize the color roles used throughout the HUD.

Usage limits

Configure rate limit display for Pro, Max, and Team subscribers.

Build docs developers (and LLMs) love

Get started for freeTalk to us