/claude-hud:configure

The /claude-hud:configure command walks you through an interactive guided flow to configure what your HUD shows and how it looks. It reads your existing config (if any), presents contextual questions, shows a preview of the result, and writes ~/.claude/plugins/claude-hud/config.json. Changes take effect immediately — no restart required.

Configure never touches advanced manual settings. The following are preserved exactly as-is during every save: colors.*, pathLevels, display.usageThreshold, and display.environmentThreshold. To change these, edit ~/.claude/plugins/claude-hud/config.json directly.

Always-on elements

These two elements are always enabled and are not configurable:

Model name — [Opus]
Context bar — ████░░░░░░ 45%

Which flow runs

Configure detects whether a config file already exists and routes accordingly:

No config → Flow A (new user): Layout → Preset → Turn Off → Turn On → Custom Line
Config exists → Flow B (update): Turn Off → Turn On → Git Style → Layout/Reset → Custom Line

Flow A: new user
Flow B: update config

For first-time configuration. Starts from a preset and lets you fine-tune.

Choose a layout

Option	What it does
Expanded (recommended)	Splits information into semantic lines — project, context, usage, activity
Compact	Everything on a single line
Compact + Separators	Single line with a visual separator before activity lines

Config written:

Layout	`lineLayout`	`showSeparators`
Expanded	`expanded`	`false`
Compact	`compact`	`false`
Compact + Separators	`compact`	`true`

Choose a preset

Presets define which elements are on or off as a starting point.

Preset	What’s included
Full (recommended)	Everything enabled — tools, agents, todos, git, usage, duration, session name
Essential	Activity lines (tools, agents, todos) + git + session duration. Info fields off.
Minimal	Core only — model name and context bar. Everything else off.

Preset element defaults:

Element	Full	Essential	Minimal
Tools activity	ON	ON	OFF
Agents status	ON	ON	OFF
Todo progress	ON	ON	OFF
Git status	ON	ON	ON
Config counts	ON	OFF	OFF
Token breakdown	ON	OFF	OFF
Usage limits	ON	OFF	OFF
Session duration	ON	ON	OFF
Session name	ON	OFF	OFF

Turn off (optional)

Shows only the elements that are on in your chosen preset. Select any you want to disable.If you chose Minimal, this step is skipped (nothing is on to turn off).

Turn on (optional)

Shows only the elements that are off in your chosen preset. Select any you want to enable.If you chose Full, this step is skipped (everything is already on).

Custom line (optional)

Optionally add a custom phrase to display in your HUD (max 80 characters). Saved as display.customLine in config.Skip this step if you don’t want a custom line.

For returning users with an existing config. Starts from your current settings.

Turn off (optional)

Shows only elements that are currently enabled. Select any you want to disable.Activity items (Tools, Agents, Todos, Project, Git) are shown first. If more than four items are currently on, bulk info items (Counts, Tokens, Usage, Speed, Duration) can be turned off together using the “Reset to Minimal” option in the Layout/Reset step.

Turn on (optional)

Shows only elements that are currently disabled. Select any you want to enable.Includes the usage bar style toggle (display.usageBarEnabled) if it is currently off.

Git style (if git is enabled)

Only shown when git status is currently enabled.

Option	What it shows	Config
Branch only	`git:(main)`	`showDirty: false`, `showAheadBehind: false`, `showFileStats: false`
Branch + dirty	`git:(main*)`	`showDirty: true`, `showAheadBehind: false`, `showFileStats: false`
Full details	`git:(main* ↑2 ↓1)`	`showDirty: true`, `showAheadBehind: true`, `showFileStats: false`
File stats	`git:(main* !2 +1 ?3)`	`showDirty: true`, `showAheadBehind: false`, `showFileStats: true`

Layout / reset

Option	Effect
Keep current	No layout or preset changes
Switch to Expanded	Change to multi-line layout
Switch to Compact	Change to single-line layout
Reset to Full	Override with Full preset (everything on)
Reset to Essential	Override with Essential preset (activity + git)

Custom line (optional)

Update, set, or remove the custom phrase shown in your HUD.

Option	Effect
Keep current	No change
Enter custom text	Set or update the phrase (max 80 chars); saved as `display.customLine`
Remove	Clears `display.customLine` (only shown if a custom line is set)

All configurable elements

Element	Config key	Default
Tools activity	`display.showTools`	`false`
Agents status	`display.showAgents`	`false`
Todo progress	`display.showTodos`	`false`
Project name	`display.showProject`	`true`
Git status	`gitStatus.enabled`	`true`
Config counts	`display.showConfigCounts`	`false`
Token breakdown	`display.showTokenBreakdown`	`true`
Output speed	`display.showSpeed`	`false`
Usage limits	`display.showUsage`	`true`
Usage bar style	`display.usageBarEnabled`	`true`
Session name	`display.showSessionName`	`false`
Session duration	`display.showDuration`	`false`
Custom line	`display.customLine`	—

Preview before saving

Before writing anything, configure shows a summary of changes and a preview of exactly how your HUD will look: Expanded layout:

[Opus | Pro] │ my-project git:(main*)
Context ████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)
◐ Edit: file.ts | ✓ Read ×3
▸ Fix auth bug (2/5)

Compact layout:

[Opus | Pro] ████░░░░░ 45% | my-project git:(main*) | 5h: 25% | ⏱️ 5m
◐ Edit: file.ts | ✓ Read ×3
▸ Fix auth bug (2/5)

You confirm before any changes are saved. If you cancel (Esc) or the result is identical to your current config, nothing is written.

Config file location

Configuration is written to:

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

The file is merged on each save — only the keys touched by the configure flow are updated. All other keys, including advanced settings, remain unchanged.

Get Started

Configuration

Commands

Guides

Development

/claude-hud:configure

Always-on elements

Which flow runs

All configurable elements

Preview before saving

Config file location

Build docs developers (and LLMs) love

Get Started

Configuration

Commands

Guides

Development

​Always-on elements

​Which flow runs

​All configurable elements

​Preview before saving

​Config file location

Build docs developers (and LLMs) love

Always-on elements

Which flow runs

All configurable elements

Preview before saving

Config file location