Claude HUD 不显示？5 类常见异常的快速修复指南-平芜编程栈

Claude HUD 不显示？5 类常见异常的快速修复指南

【免费下载链接】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 只在新消息、/compact结束、权限模式或 vim 模式切换后重跑，不是固定轮询。
确认没设置CLAUDE_HUD_DISABLE（如从 shell profile 里export出来的），它会让整个 HUD 静默。
打开~/.claude/settings.json，确认存在由/claude-hud:setup写入的statusLine配置。
旧版 Claude Code 需要重启才能加载statusLine——完全退出再跑claude。
开启调试看日志：用DEBUG=claude-hud前缀启动，观察 stderr 输出里的[claude-hud:*]行。

配置不生效

先查 JSON 语法

如果你改了~/.claude/plugins/claude-hud/config.json，重启后 HUD 还是老样子，最常见的原因是无效 JSON 被静默忽略、整体回退到默认配置，全程没有任何报错。

用 JSON 校验工具检查该文件语法，或跑node -e "JSON.parse(require('fs').readFileSync(process.env.HOME+'/.claude/plugins/claude-hud/config.json','utf-8'))"确认能解析。
核对字段取值合法：pathLevels只能是1/2/3/full，lineLayout只能是expanded或compact，maxWidth必须是正数。
删掉config.json，重跑/claude-hud:configure走一遍引导流程重新生成，等于一次重置默认配置。

检查覆盖层文件

如果config.json里明明改了、某个设置却依旧不生效，多半是覆盖层文件在更高优先级把它盖掉了。

打开~/.claude/claude-hud.json，看它是否重定义了你正想改的那个键——它和config.json结构相同，嵌套部分逐键合并、同键优先。
若你通过CLAUDE_CONFIG_DIR跑了多套配置并把plugins/软链到共享位置，确认当前生效的到底是哪个目录。
在覆盖层里同步修改或删除对应键，让config.json的值能真正生效。

状态信息不显示

Git 分支不见了

如果 HUD 第一行只剩模型和项目路径，git:(main)整块消失，通常是当前不在 git 仓库里，或该功能被关掉了。

在当前目录跑git rev-parse --abbrev-ref HEAD，确认能拿到分支名（拿不到说明目录不在仓库内）。
打开config.json，确认gitStatus.enabled为true。
需要更多信息时，按需打开showDirty（未提交星号）、showAheadBehind（↑N ↓N）、showFileStats（文件变更统计）。

用量与活动行是空的

如果第二行没有用量条，或工具、代理、待办行一直是空的，要知道这些行默认隐藏，而且各有出现前提。

打开对应开关：display.showTools、display.showAgents、display.showTodos、display.showUsage。
用量缺失时，确认登录的是 Claude 订阅账户——API Key 用户没有速率限额数据，天然不显示用量。
工具/代理/待办行除了开关，还得有对应活动才渲染：没有运行中的工具、没有进行中的待办时，行本身不出现。

显示效果不对劲

切换布局与路径长度

如果信息挤成一行看不清，或项目路径太长把别的内容顶掉了，靠lineLayout和pathLevels两个参数调节。

在/claude-hud:configure里把 Layout 切到Expanded，即lineLayout: "expanded"，按语义分行。
把pathLevels调小：1只显示项目名，2/3逐级加目录，full显示完整绝对路径。
想一行显示又要有分隔符，用lineLayout: "compact"配showSeparators: true。

倒计时不动了

如果用量重置倒计时、会话时长停在某个值不再走，原因是 Claude Code 只在交互后重跑 statusline，两次消息之间时间类信息会"冻结"。

在~/.claude/settings.json的statusLine对象里加入refreshInterval，单位秒、最小为 1。
推荐先设5，想要平滑倒计时再改成1。
重启 Claude Code 让新的刷新间隔生效。

{ "statusLine": { "type": "command", "command": "...", "refreshInterval": 5 } }

运行变慢

精简显示元素

如果开着 HUD 后终端刷新明显变卡，本质是显示元素越多、刷新越频繁，每次重渲染成本越高。

在/claude-hud:configure里选Minimal预设，只保留模型名和上下文条。
关掉开销较大的项，例如display.showMemoryUsage、display.showTools。
把refreshInterval从1调回5，或干脆去掉该键恢复"仅交互后刷新"。

解决不了怎么办

开调试日志精确定位：用DEBUG=claude-hud启动，把 stderr 里的[claude-hud:*]输出连同复现步骤一起记录。
对照 README.md 的 Troubleshooting 段落，逐条核对配置取值与账号类型。
安装本身异常（缓存与注册表不一致、LinuxEXDEV跨设备错误、ghost install）时，按 commands/setup.md 的 Step 0 自检流程清理后重装。
仍无法解决时，带着调试日志与最小复现配置，到项目 Issues 提单；渲染相关可参考 src/render/ 各模块与 src/types.ts 确认字段含义。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考