小伙伴们大家好，我是小溪，见字如面。最近在使用Claude Code CLI时因为无法实时查看上下文窗口信息，导致经常上下文频繁压缩打断开发进度体感非常不好，在逛Github时找到一个不错的项目，这里记录一下配置使用方式。

当前使用版本

2.1.156 (Claude Code)

优势

• 原生Token数据精度，无感嵌入，实时动态追踪

• 灵活的配置方式

限制

• 仅限于在Cluade Code中使用

• 高频刷新可能带来轻微开销

• Linux和Windows平台有一定限制

简介

Claude HUD 是一个专为 Claude Code 命令行工具设计的状态栏插件。它利用Claude Code的 statusline 在终端输入框下方实时展示会话状态，能够直观呈现上下文健康度、订阅限额使用率、当前活跃工具、后台运行的 Agent 以及待办任务进度，无需额外窗口或复杂配置即可大幅提升命令行开发时的交互体验与透明度。

Github地址：https://github.com/jarrodwatts/claude-hud

安装

Claude HUD是Claude Code的一个插件，需要添加插件市场进行安装。

添加插件市场

启动Claude Code CLI，在交互式命令行中输入如下命令添加插件市场

/plugin marketplaceaddjarrodwatts/claude-hud

安装插件

插件市场添加成功后，输入下面命令安装插件

/plugininstallclaude-hud

Claude Code CLI会进行插件安装界面，选择安装位置回车

安装完成后，在交互式命令中输入 /plugins 切换到【Installed】查看，看到【claude-hub】插件即为安装成功

插件安装完后执行下面命令重新加载插件

/reload-plugins

配置statusline

注意：初始化过程需要模型配合

Claude HUB插件安装完成后，在交互式命令中输入下面命令进行初始化

/claude-hud:setup

初始化完成后，可以看到如下效果：

工作原理

Claude HUD使用Claude Code原生的statusline API——无需独立窗口，不需要 tmux，在任何终端都能工作。

Claude Code → stdinJSON→ claude-hud → stdout → 在终端中显示 ↘ transcriptJSONL（工具、Agent、待办）

核心特性：

• 来自Claude Code的原生Token数据（非估算）

• 适配Claude Code报告的上下文窗口大小，包括最新的1M上下文会话

• 解析转录文件以获取工具/Agent 活动

• 约每 300ms 更新一次

功能及配置

Claude HUD提供了多种状态显示效果大致如下：

• 第 1 行：模型 + 项目名 + git 状态

• 第 2 行：上下文使用率条 + 使用配额条

• 可选行：工具活动、代理状态、todos 等

首次安装默认展示2行，可选行是不展示的，不过官方也提供了可选行的配置，目前可以通过 引导式 和 手动 2种方式进行配置

引导式配置

在Claude Code CLI中输入以下命令唤起引导式配置，根据可视化交换进行配置

/claude-hud:configure

第一步配置布局

Claude HUD提供了3种布局方式：

• 展开模式(推荐)：按语义分行展示（身份、项目、环境、用途）

• 紧凑单行模式：所有内容合并为单行

• 带分隔符紧凑模式：单行展示，行为标识前添加分隔符

为了展示最全的效果，这里我选择【展开模式】，回车后进入【预设选择】配置展示内容

Claude HUD提供了3种预设选择：

• 完整（Full）：全部启用——工具、Agent、待办、Git、使用率、时长

• 核心（Essential）：活动行 + Git 状态，减少信息冗余

• 极简（Minimal）：仅核心——只有模型名称和上下文进度条

这里我选择【Full】，回车后进入【语言选择】，这里我选择【简体中文】

回车后进入【关闭功能】，可以选择要关闭展示的状态

提交后最后进行自定义行的配置，这里我选择【3】输入自定义内容

预览配置，无误后选择【保存设置】

配置保存后，Claude Code CLI输入框底部会出现前面配置内容的状态展示，效果如下：

保存命令会创建插件配置 ~/.claude/plugins/claude-hud/config.json

完成内容如下：

{"lineLayout":"expanded","showSeparators":false,"language":"zh-Hans","display":{"showModel":true,"showContextBar":true,"showTools":true,"showSkills":true,"showMcp":true,"showAgents":true,"showTodos":true,"showProject":true,"showAddedDirs":true,"showConfigCounts":true,"showTokenBreakdown":true,"showSpeed":true,"showCost":true,"showRoutedCost":true,"showUsage":true,"showResetLabel":true,"showDuration":true,"showSessionName":true,"showSessionTokens":true,"showEffortLevel":true,"showOutputStyle":true,"showMemoryUsage":true,"showPromptCache":true,"showClaudeCodeVersion":true,"showCompactions":true,"showAdvisor":true,"customLine":"hello world"},"gitStatus":{"enabled":true,"showDirty":true,"showAheadBehind":false,"showFileStats":false}}

手动配置

手动配置Claude HUD就是直接编辑~/.claude/plugins/claude-hud/config.json，Claude HUD提供了如下配置：

• language：HUD标签语言，默认en，可选值：en | zh | zh-Hans | zh-Hant | zh-TW。设为zh/zh-Hans启用简体中文；设为zh-Hant/zh-TW启用繁体中文

• lineLayout：行布局，默认expanded，可选值：expanded（多行展开）、compact（单行紧凑）、compact-separated（带分隔符紧凑单行）

• pathLevels：项目路径显示的目录层级数，默认1，取值范围1-3

• maxWidth：备用回退宽度，默认null，类型：数字|null；仅终端宽度检测完全失效时生效

• forceMaxWidth：是否强制使用maxWidth，默认false，类型：布尔值；配置maxWidth后，该参数开启则忽略终端检测到的更小宽度，强制使用设定宽度

• elementOrder：展开模式下各元素展示顺序，默认[“project”,“context”,“usage”,“promptCache”,“memory”,“environment”,“tools”,“agents”,“todos”,“sessionTime”]，类型：字符串数组；列表中省略的内容将在展开布局隐藏，旧配置会保留自定义顺序直至更新

• display.mergeGroups：展开模式下可合并同行的相邻元素分组，默认[[“context”,“usage”]]，类型：二维字符串数组；设为空数组[]即可关闭行合并功能

• gitStatus.enabled：是否在HUD展示Git分支信息，默认true，类型：布尔值

• gitStatus.showDirty：是否显示*标记代表未提交变更，默认true，类型：布尔值

• gitStatus.showAheadBehind：是否展示提交超前/落后远程计数，默认false，类型：布尔值

• gitStatus.pushWarningThreshold：未推送提交数警告阈值，默认0，类型：数字；达到阈值后超前计数使用警告色，0代表关闭警告

• gitStatus.pushCriticalThreshold：未推送提交数严重警告阈值，默认0，类型：数字；达到阈值后超前计数使用危险色，0代表关闭严重提醒

• gitStatus.showFileStats：是否展示文件变更统计，默认false，类型：布尔值

• gitStatus.branchOverflow：超长分支名处理方式，默认truncate，可选值：truncate（截断）、wrap（换行）；truncate为直接截断文字，wrap会将Git模块单独换行展示

• display.showModel：是否展示模型名称，默认true，类型：布尔值，示例展示：[Opus]

• display.modelSource：模型名称数据来源，默认stdin，可选值：stdin | auto | transcript，stdin：默认逻辑；auto：仅代理路由返回非Claude模型时切换；transcript：始终读取API返回模型。自动清理终端转义字符，文字最大截断80字符

• display.showAddedDirs：是否展示/add-dir添加的额外工作目录，默认true，类型：布尔值；两种布局最多展示5个目录，超出显示+N more；目录名基础部分截断24字符并添加省略号…

• display.addedDirsLayout：额外目录展示样式，默认inline，可选值：inline | line，inline：和项目名称同行，前缀+目录名；line：单独一行展示Added dirs: name1,name2，无+前缀、逗号分隔

• display.showContextBar：是否展示可视化上下文进度条 ████░░░░░░，默认true，类型：布尔值

• display.contextValue：上下文用量展示格式，默认percent，可选值：percent | tokens | remaining | both，percent：百分比；tokens：总Token数；remaining：剩余占比；both：百分比+Token总数同时展示

• display.showConfigCounts：是否统计并展示CLAUDE.md、规则、MCP服务、钩子脚本数量，默认false，类型：布尔值

• display.showCost：是否显示会话消耗费用，默认false，类型：布尔值；优先读取Claude Code原生cost.total_cost_usd，无数据时本地估算

• display.showRoutedCost：是否展示第三方路由服务商（Bedrock/Vertex）费用，默认false，类型：布尔值；必须同时开启showCost才生效，原生费用有效标注Cost，Token估算标注Est.

• display.showOutputStyle：是否展示当前Claude Code输出样式，默认false，类型：布尔值；展示格式style: 样式名

• display.showDuration：是否展示会话总时长，默认false，类型：布尔值，示例：⏱️ 5m

• display.showSpeed：是否展示输出Token速率，默认false，类型：布尔值，示例：out: 42.1 tok/s

• display.showUsage：是否展示Claude订阅额度使用限制，默认true，类型：布尔值；仅订阅用户可用

• display.usageValue：订阅额度展示格式，默认percent，可选值：percent | remaining；percent=已使用占比，remaining=剩余占比

• display.usageBarEnabled：是否使用可视化进度条展示额度，默认true，类型：布尔值；关闭后仅纯文本展示

• display.usageCompact：是否启用精简额度文本，默认false，类型：布尔值；示例5h: 25% (1h 30m)，优先级高于进度条开关

• display.showResetLabel：额度倒计时前是否显示resets in前缀，默认true，类型：布尔值

• display.timeFormat：额度重置时间展示方式，默认relative，可选值：relative | absolute | both | elapsed | elapsedAndAbsolute，relative：仅倒计时；absolute：墙钟重置时刻；both：两者同时；elapsed：窗口已过百分比；elapsedAndAbsolute：已过比例+墙钟时间

• display.sevenDayThreshold：7天使用率提醒阈值，默认80，取值范围0-100；使用率≥阈值时展示，0代表永久展示

• display.externalUsagePath：本地使用率快照文件路径，默认空字符串，类型：字符串；仅标准输入缺少rate_limits数据时读取该文件

• display.externalUsageWritePath：快照写入绝对JSON路径，默认空字符串，类型：字符串；父目录必须提前存在；标准输入存在rate_limits时自动写入快照，供本地工具读取；相对路径、非JSON文件、不存在父目录会直接忽略

• display.externalUsageFreshnessMs：外部快照文件有效时长，默认300000毫秒，类型：数字；文件超过该时长会判定失效，不再读取

• display.showTokenBreakdown：高上下文（85%及以上）时是否展示Token详细数据，默认true，类型：布尔值

• display.showTools：是否展示工具运行状态行，默认false，类型：布尔值

• display.toolNameMaxLength：工具名称最大展示字符长度，默认0，类型：数字；0代表完整名称；MCP名称截断仅保留末尾段

• display.toolsMaxVisible：单行最多展示已完成工具数量，默认4，类型：数字；0代表无数量限制

• display.showAgents：是否展示代理Agent活动行，默认false，类型：布尔值

• display.showTodos：是否展示待办事项进度行，默认false，类型：布尔值

• display.showSessionName：是否展示会话标识slug或/rename自定义标题，默认false，类型：布尔值

• display.showAdvisor：是否在行内展示/advisor配置的顾问模型，默认false，类型：布尔值；示例Advisor: Opus 4.7；自动过滤控制字符、ANSI转义，最大截断64字符

• display.advisorOverride：手动自定义顾问展示文字，默认空字符串，类型：字符串；非空时优先覆盖自动读取的模型名称，同样过滤特殊字符并截断

• display.showSessionStartDate：是否展示会话创建时间戳，默认false，类型：布尔值

• display.showLastResponseAt：是否展示上一次助手响应距今时长，默认false，类型：布尔值

• display.showCompactions：是否展示会话上下文压缩次数，默认false，类型：布尔值；手动执行/compact或自动压缩都会计数，示例：压缩次数: 2；无压缩时不渲染该行

• display.showClaudeCodeVersion：是否展示本地Claude Code版本号，默认false，类型：布尔值，示例：CC v2.1.81

• display.showMemoryUsage：展开布局下是否展示近似系统内存占用，默认false，类型：布尔值

• display.showPromptCache：是否展示提示缓存倒计时，默认false，类型：布尔值；读取最后一次助手响应数据计算缓存有效期

• display.promptCacheTtlSeconds：提示缓存存活时长（秒），默认300，类型：数字；Pro版本默认300，Max版本可调整至3600

• display.customLine：自定义行内容

• colors.context：上下文进度条与百分比文字基础色，默认green，类型：颜色值

• colors.usage：额度进度条、低于警告阈值百分比文字颜色，默认brightBlue，类型：颜色值

• colors.warning：上下文超限、额度警告文本颜色，默认yellow，类型：颜色值

• colors.usageWarning：额度接近阈值时进度条与文字警告色，默认brightMagenta，类型：颜色值

• colors.critical：额度触顶、严重超限状态文字颜色，默认red，类型：颜色值

• colors.model：模型标签徽章颜色，默认cyan，类型：颜色值

• colors.project：项目路径文字颜色，默认yellow，类型：颜色值

• colors.git：Git外围括号文本颜色（git:( )），默认magenta，类型：颜色值

• colors.gitBranch：Git分支名、分支状态文字颜色，默认cyan，类型：颜色值

• colors.label：次要标签、元数据文字颜色（Context、Usage、计数等），默认dim，类型：颜色值

• colors.custom：自定义单行模块文字颜色，默认208，类型：颜色值

• colors.barFilled：进度条填充字符，默认█，类型：字符串

• colors.barEmpty：进度条空白字符，默认░，类型：字符串

下面是我精简后的配置：

{"lineLayout":"expanded","showSeparators":false,"language":"zh-Hans","display":{"showModel":true,"showContextBar":true,"showSkills":true,"showMcp":true,"showAgents":true,"showTodos":true,"showProject":true,"showAddedDirs":true,"showConfigCounts":true,"showTokenBreakdown":true,"showSpeed":true,"showCost":true,"showRoutedCost":true,"showUsage":true,"showResetLabel":true,"showDuration":true,"showSessionName":true,"showSessionTokens":true,"showEffortLevel":true,"showOutputStyle":true,"showCompactions":true,"showAdvisor":true},"gitStatus":{"enabled":true,"showDirty":true,"showAheadBehind":false,"showFileStats":false}}

配置效果如下：

友情提示

见原文：Claude HUD一款好用的Claude Code状态栏插件