Claude HUD 如何三步完成 Claude Code 状态监控插件的完整配置【免费下载链接】claude-hudA Claude Code plugin that shows whats happening - context usage, active tools, running agents, and todo progress项目地址: https://gitcode.com/GitHub_Trending/cl/claude-hud你是否遇到过Claude Code 长任务跑到一半提示上下文已满或者你根本不知道它正在读改哪个文件Claude HUD 是一款为 Claude Code 做的状态监控插件在输入框下方的状态栏实时显示上下文用量、工具活动、子代理状态和待办进度。照本文操作10 分钟内可装完并配好个性化显示。适合人群与环境前置条件适合日常使用 Claude Code 跑长会话、多代理任务、Git 项目的人。不推荐纯 API Key 用户订阅额度条不显示只能看到上下文与 Git 信息追求极简、不想任何状态栏的人装完可用环境变量临时关闭见排查手册。环境要求只有三项Claude Code v1.0.80 及以上macOS/LinuxNode.js 18 或 BunWindowsNode.js 18无需额外账号所有数据来自本地会话插件不发起网络请求能力速览Claude HUD 状态栏能看到什么能力帮你省什么事上下文用量条提前知道上下文还剩多少空间不再被上下文已满打断订阅额度条5 小时 / 7 天配额消耗一目了然关键时点不耗尽工具活动行实时看到 Claude 正在读、改、搜哪些文件子代理状态行多代理并行时看清每个代理在跑什么、跑了多久Git 分支状态不再切错分支一眼看出有无未提交改动Claude HUD 三步安装与最小配置第 1 步添加插件市场在 Claude Code 会话内执行/plugin marketplace add jarrodwatts/claude-hud这一步是登记插件来源告诉 Claude Code 去哪里找插件。第 2 步安装插件/plugin install claude-hud /reload-plugins安装后重载插件即可生效无需重启。也可以不进入会话用 CLI 执行claude plugin marketplace add jarrodwatts/claude-hud claude plugin install claude-hudclaude-hud第 3 步配置状态栏/claude-hud:setup这一步会把 statusLine 配置写入~/.claude/settings.json并自动备份旧配置完成后发下一条消息HUD 就出现在输入框下方。高频失败点如果 Linux 安装时报EXDEV: cross-device link not permitted先升级 Claude Code该 bug 已修复如果无法升级用mkdir -p ~/.cache/tmp TMPDIR~/.cache/tmp claude开启新会话后再执行安装命令如果 Windows 上 setup 提示找不到 JavaScript runtime先执行winget install OpenJS.NodeJS.LTS安装 Node.js LTS重启 shell 后重跑/claude-hud:setup跑通第一个真实任务验证你的状态栏打开任意一个 Git 项目运行claude发一条总结一下这个项目的目录结构。Claude 回复后输入框下方出现两行状态栏[Opus] │ my-project git:(main*) Context █████░░░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)第一行当前模型、项目路径、Git 分支main*的星号表示有未提交改动第二行上下文占用百分比、订阅额度消耗。再发几条消息你会看到进度条变长、百分比上升——说明数据是实时读取的来自 Claude Code 的原生令牌统计不是估算值。三个典型使用场景场景一长会话逼近上下文上限。重构大型代码库会话持续数小时。做法保持上下文条默认显示70% 转黄、85% 转红并展开令牌明细临近临界值时主动执行/compact或拆分任务。效果任务不再因上下文爆满中途断掉重来。场景二多个子代理并行探索。Claude 派出多个子代理分头查不同模块。做法运行/claude-hud:configure开启 agents 和 todos 两行。效果每个代理的类型、模型、运行时长和总体待办进度直接可见不用翻聊天记录找进展。场景三多项目频繁切分支。日常在多个仓库间跳转。做法把pathLevels调为 2 或 3 显示更多路径层级并确认gitStatus.showDirty开启。效果当前在哪个项目、哪个分支、有没有未提交改动一眼可见误提交概率大幅下降。进阶预设模式与自动刷新进阶一预设与直接编辑配置。/claude-hud:configure会引导你选布局多行/单行、预设Full 全量、Essential 精简、Minimal 最小、标签语言支持简体中文保存前可预览效果。更细的项直接编辑~/.claude/plugins/claude-hud/config.json例如改颜色{ colors: { context: cyan, warning: yellow, critical: red } }颜色支持 8 个基础名、0-255 编号或#rrggbb。配置读取逻辑见 src/config.ts。进阶二时间类信息自动刷新。Claude Code 只在每次交互后重绘状态栏所以会话时长、额度倒计时会在消息间隙停住。在~/.claude/settings.json的statusLine节点加refreshInterval秒最小 1如 5 秒即可让倒计时持续走动setup 过程中也会询问此选项。想理解渲染管线看 src/render/ 目录每行一个独立模块src/render/index.ts 负责组合。高频问题排查手册1. 状态栏不出现。判断依据发消息后输入框下方仍为空白。步骤先随便发一条消息状态栏只在交互后才渲染仍不行就完全退出并重新运行claude旧版本需要重启才能加载 statusLine 变更再检查环境变量里是否设置了CLAUDE_HUD_DISABLE该变量会让 HUD 完全静默。2. 配置改了不生效。判断依据修改 config.json 后显示与之前一致——无效的 JSON 会静默回退默认值。步骤先检查 JSON 语法漏逗号最常见确认pathLevels只取 1/2/3/full、lineLayout只取 expanded/compact拿不准就删掉配置重跑/claude-hud:configure重新生成。3. 工具/代理/待办行不显示。判断依据模型、上下文等其他行正常。原因这些行默认隐藏且只在有实际活动时出现。步骤在 config.json 将display.showTools、display.showAgents、display.showTodos设为 true或在 configure 里勾选然后让 Claude 真正执行一次文件读取或子代理任务行内容出现后才会渲染。4. 订阅额度条不显示。判断依据第二行只有 Context 没有 Usage。原因额度条仅对 Pro/Max/Team 订阅账号可用API Key 用户和 Bedrock 模型没有该数据。步骤确认登录的是订阅账号检查display.showUsage未设为 false会话刚开始时rate_limits可能为空先完成一轮对话再看。5. Git 状态不显示。判断依据第一行没有分支名。步骤确认当前目录确实在 Git 仓库内检查gitStatus.enabled未被设为 false。使用 Jujutsu 的用户注意 jj 状态是选填项需将jjStatus.enabled设为 true。项目内部速览src/index.ts入口读取 stdin JSON 并协调数据流src/transcript.ts解析会话转录提取工具、代理、待办信息src/render/各状态行的渲染模块上下文条、工具、代理等src/config.ts配置读取、默认值与合并commands/setup / configure 两个插件命令的定义下一步建议先用 Essential 预设跑一两周再按需开启 agents、tools 等行避免一开始就被信息淹没。在意倒计时实时性的话把refreshInterval设为 5每次刷新会重跑一次 HUD 命令介意开销可不设。改配置前先跑/claude-hud:configure用预览功能看效果不满意可直接回退。想本地跑起来参与贡献git clone https://gitcode.com/GitHub_Trending/cl/claude-hud cd claude-hud npm ci npm run build npm test贡献规范见 CONTRIBUTING.md测试约定见 TESTING.md。【免费下载链接】claude-hudA Claude Code plugin that shows whats happening - context usage, active tools, running agents, and todo progress项目地址: https://gitcode.com/GitHub_Trending/cl/claude-hud创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考