Configure HUD display options (layout, language, presets, display elements) while preserving advanced manual overrides
复制下面这句话，粘贴给 Claude Code、Codex、Cursor 等 AI 编程工具，它会读取安装说明并在你确认后完成安装。
请阅读 https://ai.atlankj.com/install/asset/gh-claude-hud-171effd075ce ，按照其中的说明把「configure」安装到你（当前 AI 工具）中。执行前先告诉我将运行的命令和写入的位置，等我确认。
查看 AI 将读取的安装说明正在读取 GitHub 原文…
内容来自 GitHub 原始文件，由原作者维护。在 GitHub 查看
FIRST: Resolve the active config directory ($CLAUDE_CONFIG_DIR when set, otherwise
~/.claude). Use the Read tool to load both of these files when they exist:
plugins/claude-hud/config.json inside the active config directory (the writable base).claude-hud.json directly inside the active config directory (the manual override).Store the base and override separately. The base file alone determines which flow to use. For current values and previews, compute the effective config by layering the override over the base with nested objects merged key by key and arrays/scalars replaced. Track every key defined by the override so the guided flow can identify settings that it cannot change.
These default to ON and are what most users keep. They ARE configurable
(display.showModel, display.showContextBar), but the guided flow keeps them
enabled — toggle them by editing config.json directly if needed:
[Opus]████░░░░░░ 45%Advanced settings such as colors.*, pathLevels, maxWidth, forceMaxWidth,
elementOrder, projectLineOrder, display.mergeGroups, display.timeFormat, display.contextValue,
display.modelFormat, display.modelOverride, display.modelSource, display.effortFormat, display.showProvider,
display.providerName, display.autocompactBuffer,
display.autoCompactWindow,
display.usageThreshold, display.sevenDayThreshold,
display.environmentThreshold, display.contextWarningThreshold,
display.contextCriticalThreshold, display.advisorOverride,
display.showAuth, display.showAuthUser, display.authUserLength, and the
display.externalUsage* keys, plus jjStatus.showDirty and
jjStatus.showConflicts, are preserved when saving but are not edited by this
guided flow.
Questions: Layout → Preset → Language → Turn Off → Turn On → Custom Line
Questions: Turn Off → Turn On → Git Style → Layout/Reset → Language → Custom Line (6 questions max)
Save as language: "en", language: "zh-Hans", or language: "zh-Hant".
resets in prefixNote: If preset has all items ON (Full), Q5 shows "Nothing to enable - Full preset has everything!" If preset has all items OFF (Minimal), Q4 shows "Nothing to disable - Minimal preset is already minimal!"
If user chooses "Enter custom text", use AskUserQuestion to get their text. Save as display.customLine in config.
resets in prefixIf more than 4 items ON, show Activity items (Tools, Agents, Todos, Project, Git) first. Info items (Counts, Tokens, Usage, Speed, Duration) can be turned off via "Reset to Minimal" in Q4.
resets in prefixSkip Q3 if Git is OFF - proceed to Q4.
If user chooses "Keep current", leave language unchanged.
If user chooses "English (Recommended)", save language: "en".
If user chooses "简体中文", save language: "zh-Hans".
If user chooses "繁體中文", save language: "zh-Hant".
If user chooses "Enter custom text", use AskUserQuestion to get their text. Save as display.customLine in config.
If user chooses "Remove", set display.customLine to "" in config.
Full (everything ON):
Essential (activity + git):
Minimal (core only — this is the default):
| Option | Config |
|---|---|
| Expanded | lineLayout: "expanded", showSeparators: false |
| Compact | lineLayout: "compact", showSeparators: false |
| Compact + Separators | lineLayout: "compact", showSeparators: true |
| Option | Config |
|---|---|
| English (Recommended) | language: "en" |
| 简体中文 | language: "zh-Hans" |
| 繁體中文 | language: "zh-Hant" |
| Option | Config |
|---|---|
| Branch only | gitStatus: { enabled: true, showDirty: false, showAheadBehind: false, showFileStats: false } |
| Branch + dirty | gitStatus: { enabled: true, showDirty: true, showAheadBehind: false, showFileStats: false } |
| Full details | gitStatus: { enabled: true, showDirty: true, showAheadBehind: true, showFileStats: false } |
| File stats | gitStatus: { enabled: true, showDirty: true, showAheadBehind: false, showFileStats: true } |
| Element | Config Key |
|---|---|
| Model name | display.showModel |
| Context bar | display.showContextBar |
| Tools activity | display.showTools |
| Skills activity | display.showSkills |
| MCP status | display.showMcp |
| Agents status | display.showAgents |
| Todo progress | display.showTodos |
| Project name | display.showProject |
| Added directories | display.showAddedDirs (layout via display.addedDirsLayout) |
| Git status | gitStatus.enabled |
| Jujutsu status | jjStatus.enabled |
| Config counts | display.showConfigCounts |
| Token breakdown | display.showTokenBreakdown |
| Output speed | display.showSpeed |
| Session cost | display.showCost |
| Routed provider cost | display.showRoutedCost |
| Daily cost | display.showDailyCost |
| Usage limits | display.showUsage |
| Usage bar style | display.usageBarEnabled |
| Compact usage | display.usageCompact |
| Usage value | display.usageValue |
| Usage reset label | display.showResetLabel |
| Model-scoped usage | display.showModelScopedUsage (per-model weekly windows, e.g. Fable) |
| Session name | display.showSessionName |
| Auth method | display.showAuth (plan label, e.g. "Claude Max 20x", own segment at end of first line) |
| Auth user | (login account, truncated to chars, 0 = full) |
Defaults to ON (configurable booleans, kept enabled by the guided flow):
display.showModel (default true)display.showContextBar (default true)| Option | Config | Example |
|---|---|---|
| Bar style | usageBarEnabled: true | Usage ██░░ 25% (resets in 1h 30m) |
| Text style | usageBarEnabled: false | Usage 5h 25% (resets in 1h 30m) |
| Compact | usageCompact: true | 5h: 25% (1h 30m) — no "Usage" label, shorter reset format |
usageCompact takes precedence over usageBarEnabled when both are set. Compact mode always uses the text format (no bar).
Note: Usage style only applies when display.showUsage: true. When 7d usage >= 80%, it also shows with the same style.
Set display.usageValue: "remaining" manually to show remaining quota percentages while keeping warning thresholds based on used quota.
GUARDS - Do NOT write config if:
If the user edits a key also defined by the manual override, warn before confirmation that the saved base value will remain shadowed. Show both the value being written to the base and the effective value that will still come from the override. Never edit or delete the override.
Show preview before saving:
Layout: Compact → Expanded
Language: English → 中文
Git style: Branch + dirty
Changes:
- Usage limits: OFF → ON
- Config counts: ON → OFF
[Opus | Pro] │ my-project git:(main*)
Context ████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)
◐ Edit: file.ts | ✓ Read ×3
▸ Fix auth bug (2/5)
Preview of HUD (Compact layout):
[Opus | Pro] ████░░░░░ 45% | my-project git:(main*) | 5h: 25% | ⏱️ 5m
◐ Edit: file.ts | ✓ Read ×3
▸ Fix auth bug (2/5)
Write to plugins/claude-hud/config.json inside the active config directory.
Merge with existing config, preserving:
pathLevels (not in configure flow)display.usageThreshold (advanced config)display.environmentThreshold (advanced config)display.contextWarningThreshold (advanced config)display.contextCriticalThreshold (advanced config)colors (advanced manual palette overrides)Migration note: Old configs with layout: "default" or layout: "separators" are automatically migrated to the new lineLayout + showSeparators format on load.
~/.claude/claude-hud.json (more precisely $CLAUDE_CONFIG_DIR/claude-hud.json) is an
optional overlay applied on top of config.json at load time. It uses the same shape,
only needs the keys it changes, and nested sections merge key by key:
For example, ~/.config/claude/work/claude-hud.json can contain:
{ "display": { "customLine": "Work Team" } }
This exists for users who run several CLAUDE_CONFIG_DIRs and symlink plugins/ to one
shared location - plugins/claude-hud/config.json is then the same physical file for every
directory, while this overlay stays per-directory.
Never write this file from the guided flow, and leave it untouched when it exists; it is a
manual escape hatch. Values in it win over anything written to config.json, so if a saved
setting appears not to take effect, check whether the overlay redefines it.
Say: "Configuration saved! The HUD will reflect your changes immediately."
display.showAuthUserdisplay.authUserLength| Session duration | display.showDuration |
| Session tokens | display.showSessionTokens |
| Session start date | display.showSessionStartDate |
| Last response time | display.showLastResponseAt |
| Compaction count | display.showCompactions |
| Reasoning level | display.showEffortLevel |
| Output style | display.showOutputStyle |
| Memory usage | display.showMemoryUsage |
| Prompt cache | display.showPromptCache (transcript tier wins; display.promptCacheTtlSeconds is the fallback) |
| Claude Code version | display.showClaudeCodeVersion |
| Advisor model | display.showAdvisor (override via display.advisorOverride) |
| Custom line | display.customLine |
| Custom line position | display.customLinePosition |