如何快速上手 Claude HUDClaude 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-hudClaude HUD 是一款为 Claude Code 打造的实时状态栏插件它把上下文使用量、正在调用的工具、运行中的子代理和待办进度直接显示在输入框下方始终可见。它面向每天使用 Claude Code 的开发者解决上下文还有多少余量、模型后台正在做什么这类看不见的信息。插件通过三条会话内命令即可装好这篇文章带你 10 分钟内完成安装、配置与常见用法。三分钟安装 Claude HUD 并验证运行准备工作Claude Code v1.0.80 及以上版本macOS/Linux 需要 Node.js 18 或 BunWindows 需要 Node.js 18。以下命令都在 Claude Code 会话内直接输入。添加插件市场输入/plugin marketplace add jarrodwatts/claude-hud。没有报错即成功。安装插件输入/plugin install claude-hud。Linux 用户如果报EXDEV: cross-device link not permitted通常是旧版 Claude Code 把/tmp用作了独立文件系统先在终端执行mkdir -p ~/.cache/tmp TMPDIR~/.cache/tmp claude再在新会话里重新安装。重载插件输入/reload-plugins让插件生效无需重启 Claude Code。配置状态栏输入/claude-hud:setup它会自动写入 statusLine 配置。Windows 用户若提示未找到 JavaScript 运行时先安装 Node.js LTS 再重跑该命令。发消息验证随便发一条消息回复后输入框下方应出现两行状态栏——第一行是模型、项目路径和 git 分支第二行是上下文进度条和使用率。若没有出现重启一次 Claude Code旧版本需要重启才会读取 statusLine 变更。功能地图HUD 实时展示的 5 类信息默认两行布局已覆盖最关键的信息其余行按需开启即可。上下文使用条在溢出前知道还剩多少进度条会随占比从绿色过渡到黄色、红色数据来自 Claude Code 原生上报的 token 信息不是估算值也支持 1M 级别的大上下文窗口。占比达到 85% 以上时还可以展示 token 明细方便你判断该不该执行/compact。工具活动行看清 Claude 在读写哪些文件开启showTools后工具调用会单独成行进行中的工具带旋转标记完成的带勾选和次数例如Edit: auth.ts | Read ×3 | Grep ×2。后台的文件操作从此不再是黑盒。子代理状态行并行 Agent 的进度一目了然开启showAgents后每个子代理显示名称、使用的模型、当前任务描述和已运行时长。多个 Agent 并行时你能直接看到哪个还在跑、跑了多久。待办进度行任务完成度实时更新开启showTodos后当前任务列表的完成进度如2/5始终可见不用反复追问进行到哪一步了。Git 状态与使用率限额不错分支、不超额度第一行默认显示当前分支gitStatus.showDirty会标注未提交改动*showAheadBehind可显示领先/落后远程的提交数。使用 Claude 订阅Pro/Max/Team时第二行还会显示限流使用率和重置倒计时这份数据来自订阅配额API 密钥用户以及 Bedrock/Vertex 环境不会显示。三分钟配置方法选预设再微调常用项在会话里运行/claude-hud:configure进入引导式配置先选预设再选标签语言英文、简体中文、繁体中文然后逐项开关保存前还能预览实际效果。三种预设分别是Full全开——工具、代理、待办、git、使用率、时长Essential只保留活动行 git 状态信息干扰最小Minimal仅模型名和上下文条高级项直接编辑~/.claude/plugins/claude-hud/config.json引导式配置不会覆盖你的手改内容。最小示例只保留关键字段{ lineLayout: expanded, pathLevels: 2, display: { showTools: true, showAgents: true, showTodos: true }, colors: { context: cyan, warning: yellow, critical: red } }lineLayout控制布局expanded多行或compact单行pathLevels控制项目路径显示层级1-3 或fullcolors支持预设色名、256 色编号和十六进制值。实战场景三种典型用法大项目跑长任务。关注上下文条和待办行进度条还是绿色就正常干活变黄时考虑整理变红并出现 token 明细时决定是/compact还是拆分会话。开工前顺便看一眼第一行的 git 分支确认在正确的分支上。多子代理协作。开启showAgents和showTodos然后并行派几个代理干活。盯住代理行谁运行时间明显偏长就检查它的任务描述用待办行核对整体完成度先处理卡住的任务。需要关闭或让倒计时走起来。状态栏只在交互后重新渲染所以resets in 2h 30m这类时间信息在消息之间是冻结的。想让它们持续刷新把refreshInterval秒最小 1官方建议 5加进~/.claude/settings.json的 statusLine 配置里/claude-hud:setup安装时也会提供这个选项。想临时关掉 HUD用CLAUDE_HUD_DISABLE1 claude启动会话即可无需删配置。常见报错处理状态栏完全不显示。现象setup 跑完界面底部没有状态栏。原因statusline 在你下一次交互之后才渲染或 shell 配置里设置了CLAUDE_HUD_DISABLE。解决先随便发一条消息仍不出现就重启 Claude Code再检查环境变量是否被设置。配置改完不生效。现象编辑 config.json 后显示没变化。原因JSON 有语法错误时会静默回退到默认值不报错。解决检查 JSON 语法和取值范围pathLevels只能是 1、2、3 或fulllineLayout只能是expanded或compact最省事的办法是删掉配置重跑/claude-hud:configure重新生成。工具、代理、待办行不出现。现象HUD 只有默认两行。原因这三行默认隐藏且只在有真实活动时才渲染。解决在配置里打开对应的display.showTools/showAgents/showTodos然后在会话中触发对应操作。Linux 安装报 EXDEV。现象安装过程报EXDEV: cross-device link not permitted。原因旧版 Claude Code 把/tmp独立文件系统用作临时目录。解决先升级 Claude Code无法升级就执行mkdir -p ~/.cache/tmp TMPDIR~/.cache/tmp claude后再装。使用率不显示。现象第二行只有上下文条没有使用率。原因使用率数据来自 stdin 中的订阅rate_limits纯 API 密钥用户拿不到且会话第一次模型响应前该字段可能为空。解决确认用订阅账号登录、display.showUsage未设为false按量计费的用户接受没有这一行即可。进阶指南数据流、扩展点与贡献方式HUD 的运行方式是一个stdin → stdout过程Claude Code 通过原生 statusline API 在每次渲染时推送模型、上下文等 JSON 数据HUD 同时解析会话的转录文件JSONL提取工具、代理、待办活动合并后以 300ms 防抖输出。整个过程本地完成不发起网络请求。主入口见 src/index.ts转录解析在 src/transcript.ts配置加载在 src/config.ts。想加一个新显示项路径是固定的在 src/types.ts 定义接口 → 在转录解析里补提取逻辑 → 在 src/render/ 下新建渲染模块 → 接入协调入口 src/render/index.ts → 构建并跑测试。贡献流程见 CONTRIBUTING.md本地开发只需git clone https://gitcode.com/GitHub_Trending/cl/claude-hud cd claude-hud npm ci npm run build npm test注意 PR 只改src/下的文件dist/由 CI 在合并后自动构建提交。收尾下一步该做什么Claude HUD 把 Claude Code 会话里原本不可见的上下文余量、工具动作、子代理、待办和 git 状态压缩成一条始终可见的状态栏三条命令即可完成安装。现在打开你的项目跑一次/claude-hud:setup选 Essential 预设发一条消息状态栏就该出现在输入框下方了。【免费下载链接】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），仅供参考