Claude HUD 自定义配置教程：5 步为 Claude Code 状态栏挑对布局

Claude HUD 自定义配置教程：5 步为 Claude Code 状态栏挑对布局

【免费下载链接】claude-hudA Claude Code plugin that shows what's happening - context usage, active tools, running agents, and todo progress项目地址: https://gitcode.com/GitHub_Trending/cl/claude-hud

Claude HUD 是一个 Claude Code 插件，把实时状态栏钉在输入框下方：上下文还剩多少空间、Claude 正在编辑哪个文件、有没有子代理在跑、待办进度到哪一步，一眼就能确认。安装后它默认显示两行，但布局、元素显隐和顺序都可以通过 /claude-hud:configure 做自定义配置。这篇教程按三个真实工作场景，带你挑预设、开元素、调顺序，最后验证配置生效。

🧹 场景一：只盯上下文和项目，屏幕不要多余行

默认状态下，HUD 已经有两行：第一行是模型徽标、项目路径和 Git 分支；第二行是上下文占用条，订阅账户登录时还会带一条用量条。如果你只需要这些，保持默认即可。

嫌多时，运行/claude-hud:configure，在预设一步选 Minimal。它只保留模型名和上下文条，把工具、代理、待办、用量等行全部关掉。再配合 Compact 布局，所有信息压进一行。

这套组合适合短平快的任务或较小的终端窗口——你要确认的只是"我在哪个项目、上下文满了没有"，扫一眼就够了。

🔎 场景二：想看清 Claude 在做什么、待办还剩多少

工具活动、代理状态、待办进度这三行默认是关闭的。在向导的 Turn On 一步勾选 Tools activity、Agents status、Todo progress，对应 config.json 里的display.showTools、display.showAgents、display.showTodos。

这三行是"按需出现"的：Claude 没在动文件、没有代理在跑、没有待办清单时，它们不占空间；有活动才浮出来。比如◐ Edit: auth.ts | ✓ Read ×3一行就告诉你正在编辑哪个文件、读了多少次。

用 Expanded 布局时，想让工具行排在上下文条前面，用下一节的 elementOrder 调整。

🤝 场景三：多仓库切换或团队协作，要分清自己在哪个会话

经常跨仓库工作时，把pathLevels从默认的 1 调到 2 或 3，项目路径会多显示一级父目录，例如apps/my-project。设为full则显示完整路径。

协作时有两个选项值得开。一是display.showSessionName，显示会话标题，每个会话在忙什么一眼可辨，在向导的 Turn On 一步勾 Session name 即可。二是projectLineOrder，它重排首行片段的顺序，例如["project", "model"]会把项目和 Git 状态放到模型徽标之前。这个属于高级选项，只能在 config.json 里手动编辑。

🎚️ 三种预设 Full / Essential / Minimal 怎么选：一张表定下来

预设问题是向导的第二步，三个选项的差异如下：

新用户按顺序回答 6 个问题：Layout → Preset → Language → Turn Off → Turn On → Custom Line。已有配置时走另一组 6 问：Turn Off → Turn On → Git Style → Layout/Reset → Language → Custom Line，围绕当前状态改，更直接。

向导会把结果写入~/.claude/plugins/claude-hud/config.json。保存前它会给出变更摘要和 HUD 预览，看着对再确认。

🔀 用 elementOrder 重排 HUD 元素，把工具行提到最前

默认排序来自src/config.ts里的DEFAULT_ELEMENT_ORDER数组，共 13 个元素，依次为：project、addedDirs、context、usage、promptCache、memory、environment、tools、skills、mcp、agents、todos、sessionTime。

Expanded 布局下，元素按这个数组排队。数组里没写的元素在展开模式下会被隐藏，未知名称和重复项会被静默丢弃——所以这个数组既能排序，也能当开关用。

一行改法，把工具和代理提到最前：

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

想整体手动编辑时，config.json 里的一份完整配置长这样：

{ "lineLayout": "expanded", "pathLevels": 2, "elementOrder": ["project", "tools", "context", "usage", "agents", "todos"], "gitStatus": { "enabled": true, "showDirty": true, "showAheadBehind": true, "showFileStats": true }, "display": { "showTools": true, "showAgents": true, "showTodos": true } }

🌿 Git 状态显示档位怎么挑：分支、脏标记、前后关系、文件统计

向导的 Git Style 问题对应 config.json 中gitStatus下的四个开关：

*脏标记代表有未提交更改；文件统计采用 Starship 兼容格式，!是修改、+是新增、?是未跟踪。默认档位是分支 + 脏标记，对大多数场景够用。

🩺 配置不生效：三个常见坑及排除办法

1. JSON 语法错误。无效的 JSON 会静默回退到全部默认值，HUD 不会报错。如果 HUD 突然"变回出厂"，先检查 config.json 的语法。
2. 取值越界。pathLevels只接受 1、2、3 或full，lineLayout只接受expanded或compact，越界的值会被丢弃并回退默认。
3. 被覆盖文件挡住。~/.claude/claude-hud.json（即$CLAUDE_CONFIG_DIR/claude-hud.json）是叠加在 config.json 之上的手动层，它的值永远优先。保存的设置像没生效时，先看这个文件是否重定义了同名键。

另外两个小问题：工具、代理、待办行不出现，通常是没开启，或当前确实没有活动；HUD 完全不显示时，先检查环境里有没有CLAUDE_HUD_DISABLE这个变量，它会强制状态栏保持空白。

保存配置后给 Claude 发一条任意消息，HUD 会在下一次交互时重绘，新布局即刻生效。觉得哪里还不对，再跑一次/claude-hud:configure，在 Turn Off / Turn On 里调一项、保存前看预览，逐项收敛到适合你习惯的布局。

【免费下载链接】claude-hudA Claude Code plugin that shows what's happening - context usage, active tools, running agents, and todo progress项目地址: https://gitcode.com/GitHub_Trending/cl/claude-hud