Claude HUD 不显示？配置与 Git 状态栏快速排查指南-平芜编程栈

Claude HUD 不显示？配置与 Git 状态栏快速排查指南

【免费下载链接】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 的状态栏插件，实时显示上下文用量、活动工具、运行中的代理和待办进度。装完看不到、改了配置没反应、Git 状态栏空白——按下面从上往下排一遍，几分钟就能定位。

30 秒快速自检

发消息后输入框下方什么都没出现？→ 是，看「HUD 整个不出现」
~/.claude/settings.json里有statusLine这一项吗？→ 没有，还是看「HUD 整个不出现」
HUD 在，但 Git 分支不显示？→ 是，看「Git 状态栏空白排查」
想要代理、待办进度但看不到？→ 是，看「可选信息不显示」
数字、倒计时不刷新？→ 是，看「数字不刷新」

HUD 整个不出现

statusLine 没写进配置

你装好了插件，输入框下方却空空如也。最可能的原因：没跑 setup，或 statusLine 没写进 settings.json。

在 Claude Code 里运行/claude-hud:setup
打开~/.claude/settings.json，确认存在statusLine键，且 command 里包含 claude-hud
随便发一条消息——HUD 只在一次交互之后才渲染
仍然没出现就重启 Claude Code（旧版本必须重启才加载 statusLine）

✅ 修好后你会看到这样的完整 Claude HUD 展开式布局：

改了配置不生效

改了lineLayout，界面却纹丝不动。大概率是配置文件位置不对，或 JSON 格式坏掉了。

确认配置文件路径是~/.claude/plugins/claude-hud/config.json；如果设了CLAUDE_CONFIG_DIR环境变量，文件在那个目录下的同名位置
把文件内容粘进任意 JSON 校验工具，查逗号、引号
⚠️ 格式错误、文件超过 64KB、或文件是软链接时，Claude HUD 会静默回退到默认配置，不报任何错
检查同目录下有没有claude-hud.json覆盖文件——它优先于 config.json，你以为改了，其实被它压住了

Git 状态栏空白排查

分支完全不显示

HUD 有了，git:(main)就是没有。多半是Git 状态被关掉了，或当前目录不在 Git 仓库里。

确认配置里gitStatus.enabled是true（默认就是开的）
运行/claude-hud:configure，在 Turn On 里勾选 "Git status"，保存
在项目目录手动跑git branch，确认仓库本身没问题
如果你用的是 Jujutsu 而不是 Git，要开的是jjStatus.enabled

有分支但没脏标记和文件统计

分支显示了，未提交变更不打星、文件数也不出来，是因为默认展示极简。改config.json里这三项：

"gitStatus": { "enabled": true, "showDirty": true, "showFileStats": true }

保存后发一条消息验证。showAheadBehind（领先/落后提交数）同理，默认也是关的。

可选信息不显示

代理和待办不显示

你在跑子代理、更新待办，HUD 里却看不到。这不是故障——display.showAgents和display.showTodos默认都是 false。

运行/claude-hud:configure
在 Turn On 里勾选 "Agents status" 和 "Todo progress"
保存，发一条消息确认

想看到工具活动的话，同一位置开display.showTools。

数字不刷新

上下文条、重置倒计时看着不动，是因为Claude Code 默认只在一次交互后才重跑状态栏命令，没有自动刷新。

发一条消息触发一次刷新
想要自动走动：在settings.json的statusLine对象里加"refreshInterval": 5（秒）
⚠️ 5 秒足够。设 1 秒意味着每次全量重跑（含 git 查询），大仓库会明显变卡

配置项速查

常用字段汇总如下（完整定义在 src/types.ts 里）：

字段	作用	默认值	常见错误
`lineLayout`	布局：expanded / compact	`expanded`	写成 "default" 等非法值
`showSeparators`	compact 布局加分隔符	`false`	—
`gitStatus.enabled`	是否显示 Git 状态	`true`	写成 "yes" 而非 true
`gitStatus.showDirty`	未提交变更标记	`true`	—
`gitStatus.showFileStats`	文件级变更统计	`false`	误以为默认开
`display.showAgents`	代理状态	`false`	误以为默认开
`display.showTodos`	待办进度	`false`	误以为默认开
`pathLevels`	项目路径显示层数	`1`	写 0