display key in ~/.claude/plugins/claude-hud/config.json, with the exception of lineLayout, showSeparators, pathLevels, and elementOrder which are top-level fields.
Layout
Controls whether the HUD renders on multiple lines or a single line.
expanded— model and project on line 1, context and usage on line 2, optional activity lines belowcompact— all information on a single line
Inserts a horizontal rule separator before activity lines (tools, agents, todos).
- In compact mode: separator appears between the header line and activity lines.
- In expanded mode: separator is inserted before the first activity element in the
elementOrder.
Number of directory levels to show in the project path.
1—my-project2—apps/my-project3—dev/apps/my-project
Controls the render order of elements in
expanded mode. Omit an element from the array to hide it entirely, regardless of its individual display.* setting.Valid element names: project, context, usage, environment, tools, agents, todos.Model and project
Show the current model name in brackets, e.g.
[Opus]. Always on by default; the interactive configure flow treats this as non-configurable.Show the project directory path on line 1.
Show the session slug or a custom title set via
/rename.Context bar
Show the visual context bar
████░░░░░░. Always on by default.Format used to display context window usage:
percent—45%tokens—45k/200kremaining— remaining percentage
When context usage exceeds 85%, show a breakdown of input tokens, cache creation, and cache read tokens. Automatically hidden below the threshold.
Controls whether the autocompact buffer is factored into the context percentage shown in the HUD:
enabled— shows a buffered percentage that accounts for Claude Code’s reserved autocompact space. Matches the output of/contextwhen autocompact is on.disabled— shows the raw percentage without buffering. Matches the output of/contextwhen autocompact is off.
Usage limits
Show rate limit consumption for Claude Pro, Max, and Team subscribers. Has no effect for API users or AWS Bedrock.
Controls how usage is displayed when
showUsage is true:true— visual bar:██░░░░░░░░ 25% (1h 30m / 5h)false— text only:5h: 25% (1h 30m)
Minimum usage percentage before the usage bar is shown.
0 means always show. Range: 0–100.Show the 7-day usage bar only when 7-day usage is at or above this percentage.
0 means always show. Range: 0–100.Duration and speed
Show total session duration, e.g.
⏱️ 5m.Show the output token generation speed, e.g.
out: 42.1 tok/s.Activity lines
Show a line with currently active and recently completed tool calls, e.g.:Only appears when there is tool activity to show.
Show a line with running subagent tasks, e.g.:Only appears when agents are active.
Show the current todo list progress, e.g.:Only appears when todos are present.
Environment line
Show counts of CLAUDE.md files, rules, MCP servers, and hooks, e.g.
2 CLAUDE.md | 4 rules.Minimum context usage percentage before the environment line is shown.
0 means always show when enabled. Range: 0–100.Custom line
A custom phrase displayed in the HUD. Maximum 80 characters. Set interactively via
/claude-hud:configure or by editing config.json directly.