claudeers.

🔓 unclaimed — this page was auto-generated from GitHub. Are you the creator?

Claim this page →
// Developer Tools

claude-mini-hud

对标 claude-hud 核心功能,控制在 7 行以内更轻量。内置 13 个国产大模型平台用量查询 (智谱 GLM / MiniMax / DeepSeek / Kimi / StepFun / SiliconFlow 等),第三方代理用户也能实时看到额度消耗。

// install
git clone https://github.com/zander-zyx/claude-mini-hud

📊 claude-mini-hud

Claude Code 状态栏 — 上下文 / Token / 任务 / 工具活动 / Agent 追踪 + 深度适配国产大模型用量查询

20 种进度条主题 · 4 种显示模式 · 零依赖 · 10ms 启动

简体中文 · English · 安装 · 主题预览 · FAQ · 贡献


这是什么?

claude-mini-hud 是一个 Claude Code StatusLine 插件,在你的输入框下方持续显示会话的关键指标。最多 7 行,信息密度高。对标 claude-hud 的核心功能,同时深度适配国产大模型 Coding Plan / Token Plan 用量查询。

显示效果

Ultra-Minimal (ultra-minimal) — 只保留 Context + Token 两行,极致精简:

 Context █████░░░░░ 52%  104k / 200k  剩余 96k
 Token 118k (in 89k · out 4k · cache 25k ) 12 tok/s

中文 (zh, 默认) — 完整中文 + emoji:

📊 上下文 ███░░░░░░░ 52%  104k / 200k  剩余 96k
🪙 Token 118k (入 89k · 出 4k · 缓存 25k ) 12 tok/s
💳 智谱 [pro] 5h:21% (1h54m) 7d:26% (5d7h) mcp:20/1000
▶ 当前任务 正在写 skill  (1/4)
  ◐ 读取 index.ts
  ◐ 写入 utils.ts
  ✓ 搜索 ×3  ✓ 执行 ×1
  [Explore] ◐ 搜索相关代码 2m 15s
🧠 模型 glm-5.2  [智谱]

不支持 emoji 的终端会降级为 ASCII 符号 (# $ >):

English (en):

📊 Context █████░░░░░ 52%  104k / 200k  left 96k
🪙 Token 118k (in 89k · out 4k · cache 25k ) 12 tok/s
💳 Zhipu [pro] 5h:21% (1h54m) 7d:26% (5d7h) mcp:20/1000
▶ Todos Writing skill  (1/4)
  ◐ reading index.ts
  ◐ writing utils.ts
  ✓ searching ×3  ✓ running ×1
  [Explore] ◐ Searching code 2m 15s
🧠 Model glm-5.2  [zhipu]

Minimal (minimal) — 英中混搭 + 无 emoji:

 Context █████░░░░░ 52%  104k / 200k  剩余 96k
 Token 118k (in 89k · out 4k · cache 25k ) 12 tok/s
 [B] 智谱 [pro] 5h:21% (1h54m) 7d:26% (5d7h) mcp:20/1000
 当前任务 ▸ 正在写 skill  (1/4)
  ◐ reading index.ts
  ◐ writing utils.ts
  ✓ searching ×3  ✓ running ×1
  [Explore] ◐ Searching code 2m 15s

切换: CLAUDE_MINI_HUD_LANG=zh|en|minimal|ultra-minimal (见 配置)

核心特性:

  • 零依赖: TypeScript 多模块架构,编译产物轻量
  • 🌍 四种显示模式: 中文 / English / Minimal (英中混搭) / Ultra-Minimal (只显示两行)
  • 📦 花费追踪: 本次会话累计花费 ($) + 耗时 + 花费增速 ($/h)
  • 🌿 Git 状态: 分支名 + dirty/干净标记 + ahead/behind (500ms 缓存,不拖慢刷新)
  • 填满 ETA: 按当前上下文填充速率预测"还剩多久填满",无需心算
  • ⚠️ 阈值告警: 上下文 ≥85% 或用量窗口 ≥90% 时高亮提醒
  • 📐 宽度自适应: 进度条根据终端宽度自动伸缩 (COLUMNS / stdout.columns)
  • 🎛️ 布局可配: CLAUDE_MINI_HUD_LAYOUT 自定义显示哪些行及顺序; COMPACT=1 单行紧凑模式
  • 🔧 工具活动: 实时显示文件读写、搜索、命令执行 (◐ 运行中 / ✓ 已完成×N)
  • 🤖 Agent 追踪: 显示活跃子 Agent 及其耗时
  • 🔥 Token 速率: 实时解码速度 (tok/s)
  • 📊 Token 模式: session 累计 / 上下文快照 / both 三种可切换
  • 🚀 ~10ms 启动: 不拖慢 Claude Code
  • 🔌 即插即用: /claude-mini-hud:setup 一条命令

多平台用量/余额查询

根据你的 ANTHROPIC_BASE_URL 自动检测平台,实时显示用量/余额:

平台检测条件显示格式
Claude 原生rate_limits 有数据5h:45% (1h30m) 7d:12%
MiniMaxURL 含 minimaxi.com (国内) / minimax.io (国际)5h:55% 7d:74% m:50% (26d)
智谱 (GLM)URL 含 bigmodel.cn / z.ai5h:21% (1h54m) 7d:26% m:30% (26d) mcp:20/1000
小米 (MiMo)URL 含 xiaomimimo50M/100M m:45% (26d)
阿里 (DashScope)URL 含 dashscope¥123.45 (BSS 账户余额)
火山引擎 (Ark)URL 含 volces.com平台识别 (暂无公开用量 API)
百度千帆 (Qianfan)URL 含 qianfan / baidubce平台识别 (暂无公开用量 API)
腾讯混元 (Hunyuan)URL 含 hunyuan平台识别 (暂无公开用量 API)
讯飞星辰 (Astron)URL 含 xfyun / spark-api平台识别 (包月订阅)
DeepSeekURL 含 deepseek.com¥123.45 (账户余额)
KimiURL 含 moonshot.cn / moonshot.ai¥42.50 (赠送 ¥10.00)
Kimi For CodingURL 含 api.kimi.com/coding5h:42% (1h23m) 7d:15%
阶跃星辰 (StepFun)URL 含 stepfun.com (国内) / stepfun.ai (国际)¥42.50 (代金券 ¥10.00)
硅基流动 (SiliconFlow)URL 含 siliconflow.cn (国内) / siliconflow.com (国际)¥42.50 (赠送 ¥10.00)

用量显示格式说明

标签含义示例
5h:5小时窗口用量5h:19% (1h54m) — 已用 19%, 1小时54分后重置
7d:7天 (周) 用量7d:26% (5d7h) — 已用 26%, 5天7小时后重置
m:月度用量m:30% (26d) — 已用 30%, 26天后重置 (只显示天数)
mcp:MCP 工具调用次数mcp:20/1000 — 已调用 20 次 / 总限额 1000 次
固定额度TOKEN PLAN 已用/总额50M/100M — 大数自动用 M/k 单位

💡 无需额外配置 — 只要设了 ANTHROPIC_BASE_URLANTHROPIC_AUTH_TOKEN,插件自动识别平台并查询。

🍪 小米 (MiMo) 需要额外设置 XIAOMI_COOKIE 环境变量 (从浏览器 DevTools 获取 Cookie),因为小米用量 API 使用 Cookie 认证而非 API Key。

🔑 阿里 (DashScope) 账户余额查询走阿里云 BSS OpenAPI,需要设置 ALIYUN_AK_ID + ALIYUN_AK_SECRET(主账号 RAM 密钥,不是 DASHSCOPE_API_KEY)。DashScope 本身没有公开余额 API。

claude-hud 的定位

jarrodwatts/claude-hud 是全功能状态栏 (10+ 行),主要面向 Anthropic Claude 原生用户。本项目在信息密度和简洁之间取得平衡,核心思路有两点:

  1. 对标 claude-hud 核心功能 — 工具活动、Agent 追踪、Task 解析等能力一个不少,但控制在 7 行以内,比 claude-hud 更轻量
  2. 深度适配国产大模型 — 内置智谱 GLM、MiniMax、小米 MiMo、阿里 DashScope、火山引擎 Ark、百度千帆、腾讯混元、讯飞星辰、DeepSeek、Kimi、Kimi For Coding、阶跃星辰 StepFun、硅基流动 SiliconFlow 等平台的 Coding Plan / Token Plan 用量查询,使用第三方代理的用户也能在状态栏实时看到额度消耗

📑 目录


前置条件

在安装本插件之前,请确认:

依赖最低版本检查命令说明
Claude Code CLI≥ 2.0claude --version支持 StatusLine 的最低版本,推荐 ≥ 2.1.6 (百分比更准)。安装文档
Node.js≥ 18.0.0node --version用于编译 TypeScript
npm≥ 9.0npm --version装 TypeScript
TypeScript≥ 5.4npx tsc --version编译时自动装

💡 零运行时依赖 — 编译产物是纯 Node.js,不依赖任何 npm 包。


30 秒快速体验

最快看到效果的方法 (适合想"先看看"的人):

# 1. 克隆到本地
git clone https://github.com/zander-zyx/claude-mini-hud.git
cd claude-mini-hud

# 2. 编译
npm install
npm run build

# 3. 测试一下输出
echo '{"model":{"display_name":"MiniMax-M3"},"context_window":{"current_usage":{"input_tokens":22000,"output_tokens":342,"cache_creation_input_tokens":768},"context_window_size":200000}}' | node dist/index.js

预期输出 (含 ANSI 颜色):

📊 上下文 ███░░░░░░░ 13%  22.0k / 200.0k  剩余 178k
🪙 Token 23.1k (入 22.0k · 出 342 · 缓存 768 )

看到这两行?说明一切正常。下一步:安装到 Claude Code


安装

方式 0: 让 Claude 自己装 (最省心)

不想看下面这些步骤?直接把下面这段话复制粘贴到 Claude Code 对话框,让 Claude 替你完成全部安装:

帮我安装 claude-mini-hud 状态栏插件:
1. 执行 /plugin marketplace add zander-zyx/claude-mini-hud
2. 执行 /plugin install claude-mini-hud
3. 执行 /reload-plugins
4. 执行 /claude-mini-hud:setup 完成配置 (语言选中文, 主题按我喜好推荐)
5. 完成后告诉我需要重启 Claude Code

💡 Claude 会按顺序执行斜杠命令并引导你完成 setup 菜单。装完后重启 Claude Code 即可看到状态栏。


方式 1: Marketplace (推荐)

最简单。Claude Code 会自动拉代码 + 编译 + 配置。

# 1. 在 Claude Code 内,添加 marketplace
/plugin marketplace add zander-zyx/claude-mini-hud

# 2. 安装插件
/plugin install claude-mini-hud

# 3. 重载插件缓存
/reload-plugins

# 4. 跑 setup (依次弹出菜单: 语言 / 进度条主题 / 工具标记)
/claude-mini-hud:setup

✅ 完成!重启 Claude Code,输入框下方应看到状态栏。

setup 流程会:

  1. 检测你的操作系统和 Claude 配置目录
  2. 选择语言 (中文 / English / 简约 Minimal / 极简 Ultra-Minimal)
  3. 选择进度条主题 + 工具标记风格 (可选, 20 种主题自由组合, 默认经典)
  4. 检查现有 statusLine 配置,如有冲突会备份
  5. node <path>/dist/index.js + 环境变量写入 ~/.claude/settings.json
  6. 提示重启 + 验证步骤

方式 2: 手动 git clone

适合想自己控制路径,或调试时改代码立即生效的人。

Linux / macOS:

# 1. 克隆到 Claude 插件目录 (version 是目录名一部分,改版本时同步改)
git clone https://github.com/zander-zyx/claude-mini-hud.git \
  ~/.claude/plugins/cache/local/claude-mini-hud/1.2.0

# 2. 进入目录编译
cd ~/.claude/plugins/cache/local/claude-mini-hud/1.2.0
npm install
npm run build

# 3. 把 statusLine 写入 ~/.claude/settings.json
# 用 jq / 编辑器都行,关键字段:
{
  "statusLine": {
    "type": "command",
    "command": "node ~/.claude/plugins/cache/local/claude-mini-hud/1.2.0/dist/index.js"
  }
}

# 4. 重启 Claude Code

💡 目录命名规范:Claude Code 期望 {vendor}/{name}/{version}/ 三级结构。local 是 vendor,claude-mini-hud 是 name,1.0.0 是 version。改代码时不要改 version,否则 Claude Code 认为是新插件,会重新跑一次缓存逻辑。

方式 3: Windows PowerShell

# 1. 克隆
git clone https://github.com/zander-zyx/claude-mini-hud.git $env:USERPROFILE\.claude\plugins\cache\local\claude-mini-hud\1.2.0

# 2. 编译
cd $env:USERPROFILE\.claude\plugins\cache\local\claude-mini-hud\1.2.0
npm install
npm run build

# 3. 设置 statusLine (PowerShell 写法)
$settings = Get-Content $env:USERPROFILE\.claude\settings.json -Raw | ConvertFrom-Json
$settings | Add-Member -Type NoteProperty -Name statusLine -Value @{
  type = "command"
  command = "node $env:USERPROFILE\.claude\plugins\cache\local\claude-mini-hud\1.2.0\dist\index.js"
}
$settings | ConvertTo-Json -Depth 10 | Set-Content $env:USERPROFILE\.claude\settings.json

# 4. 重启 Claude Code

Linux tmpfs 修复

如果安装时报:

EXDEV: cross-device link not permitted

这是因为 /tmp~/.claude不同的文件系统 (tmpfs vs ext4) — Claude Code 想用 hardlink 但跨设备不允许。

解决方案:

mkdir -p ~/.cache/tmp
TMPDIR=~/.cache/tmp claude
# 在这个 session 里跑 /plugin install

这是 Claude Code 平台限制,非本插件问题。


使用

看到的输出

全部启用 (中文 + 模型 + 工具活动 + Agent 追踪):

📊 上下文 ███░░░░░░░ 13%  100k / 1M  剩余 900k
🪙 Token 4.8M (入 3.5M · 出 1.2M · 缓存 103k ) 45 tok/s ~2h40m 填满
⚠ 告警 上下文即将耗尽 88%
▶ 当前任务 正在写 skill  (1/4)
  ◐ 读取 index.ts
  ◐ 写入 utils.ts
  ✓ 搜索 ×3  ✓ 执行 ×1
  [Explore] ◐ 搜索相关代码 2m 15s
🧠 模型 glm-5.2  [智谱]
$ 花费 $0.42 · 3m 12s · $1.20/h
⎇ 分支 main ●

无工具/Agent 时 (自动隐藏对应行, 仅 3 行):

📊 上下文 ███░░░░░░░ 13%  100k / 1M  剩余 900k
🪙 Token 4.8M (入 3.5M · 出 1.2M · 缓存 103k ) ~2h40m 填满
▶ 当前任务 调研充电行业政策  (2/5)

显示时机

状态栏在以下时刻自动刷新:

  • 每次 Claude 响应结束
  • 每次你发新消息
  • 每次 todo list 变化 (开始 / 完成 / 切换 in-progress)

它不影响 Claude Code 性能:渲染是异步的,不到 10ms,不抢主进程 CPU。


配置

环境变量详解

变量默认可选值说明
CLAUDE_MINI_HUD_LANGzhzh / en / minimal / ultra-minimal界面语言 (minimal = 英中混搭 + 无 emoji, ultra-minimal = 只显示 Context + Token 两行)
CLAUDE_MINI_HUD_THEMEdefault21 种,见主题预览进度条风格
CLAUDE_MINI_HUD_MARKSdefault21 种,见主题预览工具/Agent 标记图标 (独立于进度条, 可自由组合)
CLAUDE_MINI_HUD_SHOW_MODEL(未设)1设置为 1 时显示模型行
CLAUDE_MINI_HUD_TOKEN_MODEsessionsession / context / bothToken 行模式: session=累计 / context=快照 / both=两行
CLAUDE_MINI_HUD_NO_EMOJI(未设)1设置为 1 时强制禁用 emoji, 使用 ASCII 符号 (# $ > 等)
CLAUDE_MINI_HUD_SHOW_COST(未设)1显示花费行: 累计 $ + 耗时 + 花费增速 $/h (读 stdin.cost)
CLAUDE_MINI_HUD_SHOW_GIT(未设)1显示 Git 行: 分支名 + dirty/干净标记 + ahead/behind (spawn git, 500ms 缓存)
CLAUDE_MINI_HUD_WARN1 (开)0 / 1设为 0 关闭阈值告警; 默认开启, 上下文 ≥85% 或任一用量窗口 ≥90% 时高亮提醒
CLAUDE_MINI_HUD_COMPACT(未设)1单行紧凑模式: 把 上下文% / 用量 / 花费 / 当前任务 / ETA 用 压成一行
CLAUDE_MINI_HUD_LAYOUT(未设)逗号分隔行名自定义显示哪些行及顺序, 可用: context,token,usage,alert,todo,tools,agent,cost,git,model
CLAUDE_MINI_HUD_RED_PCT800-100红色阈值: 百分比 ≥ 此值显示红色 (Context / 用量窗口 / 月度统一生效)
CLAUDE_MINI_HUD_YELLOW_PCT600-100黄色阈值: 百分比 ≥ 此值显示黄色, < 红色阈值
CLAUDE_MINI_HUD_BG(自动)light / dark终端背景色, 用于颜色对比度适配。未设时自动读 COLORFGBG / TERM_BACKGROUND_COLOR, 默认 dark
CLAUDE_MINI_HUD_DEBUG(未设)1调试模式: 输出各模块 (usage 查询/缓存) 的错误信息到 stderr, 用于排查"用量行不显示"等问题

在 statusLine.command 里设置 (推荐):

Linux / macOS:

// ~/.claude/settings.json
{
  "statusLine": {
    "type": "command",
    "command": "CLAUDE_MINI_HUD_LANG=en CLAUDE_MINI_HUD_THEME=arrow node ~/.claude/plugins/cache/local/claude-mini-hud/1.2.0/dist/index.js"
  }
}

Windows (需要 PowerShell 包装):

// %USERPROFILE%\.claude\settings.json
{
  "statusLine": {
    "type": "command",
    "command": "powershell -NoProfile -Command \"$env:CLAUDE_MINI_HUD_LANG='en'; $env:CLAUDE_MINI_HUD_THEME='arrow'; node '%USERPROFILE%\\.claude\\plugins\\cache\\local\\claude-mini-hud\\1.2.0\\dist\\index.js'\""
  }
}

主题预览

以下效果均在 72% 上下文使用率 时展示。

主题环境变量值进度条效果工具标记
经典default# Context ███████░░░ 72%◐ 运行中 ✓ 已完成
霓虹矩阵neon⟦ CTX: ▓▓▓▓▓▓▓░░░ 72% ⟧◈ 运行中 ✦ 已完成
Braille 点阵braille# Context ⣿⣷⣯⣟⡿⣯⣟░░░░ 72%⣷ 运行中 ⣿ 已完成
硬核hardcore[■■■■■■■□□□] 72% CTX │● 运行中 ■ 已完成
超简约minimal◈ 72% ┃ 125k / 200k left 75k· 运行中 · 已完成
像素pixel# Context ⣿⣿⣿⣿⣿⣿⣿⣀⣀⣀ 72%▣ 运行中 ■ 已完成
钻石diamond# Context ◆◆◆◆◆◆◆◆◇◇ 72%◈ 运行中 ◆ 已完成
箭头arrow# Context ▸▸▸▸▸▸▸▸▹▹ 72%▸ 运行中 ✓ 已完成
波浪wave# Context ≋≋≋≋≋≋≋≋∿∿ 72%≋ 运行中 ≈ 已完成
潮汐tide# Context ∿∿∿∿∿∿∿∿╌╌ 72%∿ 运行中 ≈ 已完成
圆点dot# Context ●●●●●●●●○○ 72%◉ 运行中 ● 已完成
靶心target# Context ◎◎◎◎◎◎◎◎⊙⊙ 72%◎ 运行中 ⊙ 已完成
阴影shades# Context █▓▒░█▓▒░·· 72%▒ 运行中 █ 已完成
复古终端retro# Context ════════▸─── 72%► 运行中 ■ 已完成
纯 ASCIIascii# Context ##########.... 72%@ 运行中 # 已完成
铁轨rail# Context ══════════╌╌ 72%╌ 运行中 ═ 已完成
星光star# Context ⭐⭐⭐⭐⭐⭐⭐⭐☆☆ 72%☆ 运行中 ⭐ 已完成
火花spark# Context ✦✦✦✦✦✦✦✦✧✧ 72%✦ 运行中 ✧ 已完成
心形heart# Context 🖤🖤🖤🖤🖤🖤🖤🤍🤍🤍 72%💗 运行中 🖤 已完成
爱心love# Context ❤️❤️❤️❤️❤️❤️❤️🤍🤍🤍 72%💗 运行中 ❤️ 已完成

💡 自由组合: CLAUDE_MINI_HUD_THEME 控制进度条, CLAUDE_MINI_HUD_MARKS 控制工具/Agent 标记, 两者独立可混搭。例如 THEME=hardcore MARKS=diamond

💡 为什么用 env 而非配置文件? 零依赖哲学的延伸 — 不创建任何配置文件,不污染用户项目目录,跟 Claude Code 自身的 env 配置 (ANTHROPIC_BASE_URL 等)风格一致。

显示字段说明

内容触发条件渲染函数
# 上下文进度条 + % + used / total + 剩余✅ 必显renderContextLine
$ Token累计 in/out/cache + ⚡速率✅ 必显renderTokenLine
[B] 用量/余额多平台用量百分比 / 余额有用量数据时renderUsageLine
> 当前任务in-progress todo + 完成度有 todo 时renderTodoLine
[*] 工具◐ 运行中 / ✓ 已完成×N有工具活动时renderToolActivityLines
& Agent◐ 描述 + 耗时有活跃 Agent 时renderAgentLines
> 模型模型名 + provider 标签SHOW_MODEL=1renderModelLine
$ 花费累计 $ + 耗时 + $/h 增速SHOW_COST=1renderCostLine
⎇ 分支分支名 + dirty/干净 + ahead/behindSHOW_GIT=1renderGitLine
⚠ 告警上下文/用量阈值提醒默认开 (WARN=0 关)renderAlertLine

Token 行字段详解

$ Token 4.8M (入 3.5M · 出 1.2M · 缓存 103k ) 各部分含义:

字段来源用途
入 / intotal_input_tokens (stdin) 或 transcript 累加本次会话累计输入 token
出 / outtotal_output_tokens (stdin) 或 transcript 累加本次会话累计输出 token
缓存 / cachecache_creation_input_tokens + cache_read_input_tokensprompt cache 命中
tok/s两次 StatusLine 刷新的 output_tokens 差值实时解码速度

📌 Token 来源优先级:

  1. stdin total_input_tokens / total_output_tokens (Claude Code 上报的 session 累计)
  2. transcript 尾部 message.usage 累加 (fallback)
  3. current_usage 快照 (最后的兜底)

进度条颜色阈值

百分比颜色含义
< 60%🟢 绿健康
60-80%🟡 黄注意
> 80%🔴 红接近上限,考虑 /clear

Provider 检测 (模型行启用时)

Provider 标签触发条件
BedrockCLAUDE_CODE_USE_BEDROCK=1
VertexCLAUDE_CODE_USE_VERTEX=1
Enterprise模型 id 是 opusplan / sonnetplan / haikuplan
自定义 (如 minimaxi)ANTHROPIC_BASE_URL 指向非 anthropic.com

自定义

改显示文字 / emoji

直接改 src/i18n.ts 里的 STRINGS 表:

const STRINGS = {
  zh: {
    context: '上下文',     // 改成 'Ctx' 也行
    token: 'Token',
    in: '入',               // 改成 '↓' 也行
    out: '出',              // 改成 '↑'
    cache: '缓存',          // 改成 '⚡'
    // ...
  },
  en: {
    context: 'Context',
    // ...
  },
};

改完:

npm run build   # 重新编译
# 重启 Claude Code

改进度条风格

通过环境变量切换 (无需改代码):

CLAUDE_MINI_HUD_THEME=arrow  # 可选: default/neon/braille/hardcore/minimal/pixel/diamond/arrow/wave/tide/dot/target/shades/retro/ascii/rail/star/spark/heart

或自定义主题,修改 src/themes.ts 中的 ThemeConfig:

export interface ThemeConfig {
  filled: string[];    // 填充字符 (如 ['█'], ['◆'], ['▸'])
  empty: string;       // 空白字符 (如 '░', '◇', '▹')
  leftBorder: string;  // 左边框 (如 '[', '⟦', '')
  rightBorder: string; // 右边框 (如 ']', '⟧', '')
  width: number;       // 进度条宽度 (默认 20)
  // ...
}

改进度条颜色阈值

v1.2.0 起,颜色阈值已集中为环境变量,无需改源码:

# 红色阈值 (默认 80): 百分比 ≥ 此值显示红色
CLAUDE_MINI_HUD_RED_PCT=90

# 黄色阈值 (默认 60): 百分比 ≥ 此值显示黄色
CLAUDE_MINI_HUD_YELLOW_PCT=70

写进 statusLine.command 即可,对所有百分比生效(Context / 用量窗口 / 月度)。

💡 如果需要更精细的控制(如 Context 和 Usage 分开阈值),再改 src/render.ts 里的 RED_PCT / YELLOW_PCT 常量定义。

改 Token 行格式

renderTokenLine 函数:

const parts = [
  `${c.gray('↓')} ${inStr}`,     // 用箭头代替 "in"
  `${c.gray('↑')} ${outStr}`,
];
if (breakdown.cache > 0) {
  parts.push(`${c.gray('⚡')} ${cacheStr}`);
}

添加自定义行 (内置 Git 分支已可直接用)

本插件已内置 Git 分支行 (CLAUDE_MINI_HUD_SHOW_GIT=1 即可), 下方示例演示如何添加全新的自定义行。新增行需在 src/index.tsmain() 里注册到 layout producers:

async function renderGitBranchLine(): Promise<string | null> {
  try {
    const { execSync } = await import('node:child_process');
    const branch = execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8' }).trim();
    return `${c.gray('🌿')} ${branch}`;
  } catch {
    return null;
  }
}

// main() 里:
const branchLine = await renderGitBranchLine();
if (branchLine) lines.push(branchLine);

FAQ

Q: 安装后只看到一行 fallback "claude-mini-hud — 渲染失败"

A: statusLine.command 路径不对,或 Node.js 找不到。

排查:

# 1. 检查 dist/index.js 是否存在
ls -la ~/.claude/plugins/cache/local/claude-mini-hud/1.2.0/dist/index.js

# 2. 手动测试,看 stdout 有没有内容
echo '{"model":{"display_name":"test"}}' | node ~/.claude/plugins/cache/local/claude-mini-hud/1.2.0/dist/index.js
# 应该输出: 📊 上下文 ... 🪙 Token ...

# 3. 如果手动跑 OK 但 Claude Code 里没显示,检查 settings.json
cat ~/.claude/settings.json | grep -A2 statusLine

Q: 进度条一直是 0%

A: 你用的是 Claude Code v2.1.5 及以下,它不传 used_percentage 字段。本插件会回退到手算 token 百分比,如果 token 数据也空就显示 0%。

v1.0.0+ 已加入 Context 百分比防闪烁机制:当 Claude Code 发送的某帧数据所有 token 字段为零/缺失时,自动使用 5 分钟内的上次有效百分比缓存,避免进度条闪烁归零。/clear 后缓存自动过期,不会残留旧值。

如果仍然频繁出现 0%: 升级到最新版 Claude Code:

npm update -g @anthropic-ai/claude-code

Q: Token 行的 out 一直显示 0

A: Claude Code v2.x 在 current_usage省略 output_tokens 字段。本插件会自动从 transcript.jsonl 累加,如果 transcript_path 路径不对就读不到。

解决: 检查 ~/.claude/settings.jsontranscriptPath (在 claude config 内部,不是 statusLine) 是否可读。

Q: 中文显示乱码

A: 你的终端不支持 UTF-8。检查 locale:

locale   # 应含 UTF-8
echo $LANG

如果是 POSIXC,改成:

export LANG=en_US.UTF-8
# 或 zh_CN.UTF-8

Q: 可以只显示某一行吗?

A: 直接改 main() 函数,删掉不想渲染的行:

async function main() {
  // ...
  lines.push(renderContextLine(stdin));
  // lines.push(renderTokenLine(...));  // 注释掉 = 不显示 Token
  // ...
}

Q: 跟 claude-hud 能同时装吗?

A: 不行。两者都用 statusLine.command,后装的覆盖先装的。如果你想 A/B 测试,在 ~/.claude/settings.json 切换 command 即可。

Q: 升级版本怎么操作?

A:

cd ~/.claude/plugins/cache/local/claude-mini-hud/1.2.0
git pull
npm install
npm run build
# 重启 Claude Code

Q: Windows 上 node 找不到

A: 安装 Node.js LTS,确保 PATH 含 Node.js 安装目录。或者在 statusLine.command 里用绝对路径:

"command": "C:\\Program Files\\nodejs\\node.exe C:\\Users\\you\\.claude\\..."

Q: 安装慢 / GitHub 不可达 (中国大陆用户)

A: 默认情况下,从 GitHub clone + npm install 在国内可能很慢或失败。解决方案:

# 1. 用 npmmirror 加速 npm
npm config set registry https://registry.npmmirror.com

# 2. 用 CNB 镜像 clone (如果 GitHub 直接不通)
git clone https://cnb.cool/zdking/claude-mini-hud.git

# 3. 用 SSH over port 443 (绕过 GFW 对 22 端口的限速)
# ~/.ssh/config:
#   Host github.com
#     HostName ssh.github.com
#     Port 443
#     User git

本项目 README / 代码全部用 ASCII + 通用 UTF-8 emoji,在任何 locale 下渲染都没问题。

Q: 想贡献但不知道从哪开始

A: 看 贡献章节。新手友好的 issues 标了 good first issue 标签。


开发

跨平台编译 (Windows / macOS / Linux)

项目用纯 TypeScript + Node.js, 不依赖任何二进制或原生模块. 编译只需:

npm install        # 装 typescript + tsx + @types/node
npm run build      # tsc 编译 src/ → dist/

两个 tsconfig 文件:

  • tsconfig.json: 主配置, 只编译 src/, 产物输出到 dist/
  • tsconfig.test.json: 类型检查 tests/, noEmit: true 不写文件

为什么两个 tsconfig? 单 tsconfig 的话, rootDir: "./src"include: ["tests/**/*"] 会冲突 (tests 不在 src 下, TypeScript 报 "TS6059"). 拆分后两边都干净.

跑测试

npm install
npm test            # build + typecheck + 跑 36 个测试 (用 tsx 直接跑 ts 测试)
npm run test:stdin  # 手测单个 stdin 输入
npm run typecheck   # 只做类型检查, 不 emit

开发模式

npm run dev   # tsc --watch, 自动重新编译
# 另开一个终端:
echo '{"model":{"display_name":"dev"}}' | node dist/index.js

测试覆盖 (43 个用例)

#用例验证
1cli 接受 stdin JSON 并输出必显行context + token 行
2默认不显示模型行默认隐藏
3CLAUDE_MINI_HUD_SHOW_MODEL=1 显示模型行env 生效
4空 stdin 输出 fallback错误处理
5进度条在 > 80% 时使用红色颜色阈值
6进度条在 < 60% 时使用绿色颜色阈值
7上下文行格式 used/total + 剩余100k / 1M 格式
8Token 行细分 in/out/cache数值精确匹配
9从 transcript_path 读取 todosin_progress + 1/3
10provider 检测 (minimaxi)SHOW_MODEL=1 时输出
11CLAUDE_MINI_HUD_LANG=zh 默认中文中文 label
12CLAUDE_MINI_HUD_LANG=en 显示英文无中文 marker
13CLAUDE_MINI_HUD_LANG=minimal 无 emoji + 英中混搭混合输出验证
14–26多平台检测 (claude/deepseek/minimax/minimax.io/kimi-coding/null/kimi/moonshot.ai/zhipu/z.ai/xiaomi/alibaba/volcengine)URL 匹配 (含国际站)
26–36缓存读写 + 端到端 + MiniMax 模型匹配tests/usage.test.ts (23 用例)

项目结构

claude-mini-hud/
├── README.md           # 本文件 (中文)
├── README.en.md        # 英文 README
├── LICENSE             # MIT
├── package.json        # npm 元数据 + scripts
├── tsconfig.json       # TypeScript 配置 (编译 src/ → dist/)
├── tsconfig.test.json  # TypeScript 测试配置 (仅类型检查)
├── CLAUDE.md           # Claude Code 项目指引
├── .gitignore
├── .claude-plugin/
│   └── plugin.json     # Claude Code 插件描述
├── commands/
│   └── setup.md        # /claude-mini-hud:setup 入口
├── src/
│   ├── index.ts        # 入口 + stdin 读取 + main()
│   ├── types.ts        # 共享类型定义
│   ├── i18n.ts         # 国际化 (zh/en/minimal)
│   ├── colors.ts       # ANSI 颜色 (零依赖)
│   ├── themes.ts       # 进度条主题系统 (20 种可选)
│   ├── render.ts       # 所有渲染函数
│   ├── transcript.ts   # Transcript JSONL 解析
│   └── usage.ts        # 多平台用量/余额查询
└── tests/
    ├── stdin.test.ts   # 状态栏渲染测试 (13 用例)
    └── usage.test.ts   # 多平台用量查询测试 (23 用例)

贡献

欢迎 PR!以下是贡献指南:

提 Issue

Bug 报告请包含:

  • Claude Code 版本 (claude --version)
  • Node.js 版本 (node --version)
  • 操作系统 (macOS 14 / Ubuntu 22.04 / Windows 11 等)
  • 复现步骤 (尤其是 statusLine.command 完整内容)
  • 期望输出 vs 实际输出 (ASCII 截图最好)

功能请求请说明:

  • 解决什么场景?
  • 为什么现有 7 行还不够?
  • 能否在不改 API 的情况下加进现有字段?

提 PR

  1. Fork 这个仓库
  2. 创建分支: git checkout -b feat/your-feature
  3. 跑测试: npm test (必须全过)
  4. 提交: git commit -m "feat: ..."
  5. 推送: git push origin feat/your-feature
  6. 开 PR,描述改了啥 + 截图

代码风格

  • TypeScript strict mode
  • 不用第三方依赖 (除非有极强理由,先开 issue 讨论)
  • 保留中文/英文双语字符串
  • 加新字段时同步更新 README + 测试

Roadmap

近期 (v1.1):

  • 进度条主题系统 (20 种风格: 经典/霓虹/点阵/硬核/简约/像素/钻石/箭头/波浪/潮汐/圆点/靶心/阴影/复古/ASCII/铁轨/星光/火花/心形/爱心)
  • Session 费用显示 (花费/耗时/$/h, CLAUDE_MINI_HUD_SHOW_COST=1)
  • Git 分支/dirty 状态 (CLAUDE_MINI_HUD_SHOW_GIT=1)
  • 上下文填满 ETA (按当前速率预测填满耗时)
  • 阈值告警行 (CLAUDE_MINI_HUD_WARN)
  • 终端宽度自适应进度条
  • 布局配置 (CLAUDE_MINI_HUD_LAYOUT) + 单行紧凑模式 (COMPACT=1)
  • 多窗口切换时更平滑的刷新
  • 从环境变量读取颜色阈值

中期 (v1.2):

  • 亮色/暗色主题适配
  • 鼠标悬停提示 (受 Claude Code TUI 限制)
  • 可点击的状态栏链接 (跳转到当前 transcript)

相关项目

项目风格适合谁
claude-mini-hud (本项目)轻量, 最多 7 行喜欢清爽, 只要核心指标
claude-hud全功能,10+ 行想要 git 状态 / agents / 工具统计
tweakcc配置 / prompt 级想改 Claude Code 本身行为

License

MIT © 2026 Zander Zhang — 详见 LICENSE


致谢


Star History

如果这个项目帮到你,给个 ⭐ 让更多人看到!

Star History Chart

English

See README.en.md.

// compatibility

Platformscli, api
Operating systems
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageTypeScript

// faq

What is claude-mini-hud?

对标 claude-hud 核心功能,控制在 7 行以内更轻量。内置 13 个国产大模型平台用量查询 (智谱 GLM / MiniMax / DeepSeek / Kimi / StepFun / SiliconFlow 等),第三方代理用户也能实时看到额度消耗。. It is open-source on GitHub.

Is claude-mini-hud free to use?

claude-mini-hud is open-source under the MIT license, so it is free to use.

What category does claude-mini-hud belong to?

claude-mini-hud is listed under devtools in the Claudeers registry of Claude-compatible tools.

0 views
10 stars
unclaimed
updated about 4 hours ago

// embed badge

claude-mini-hud on Claudeers
[![Claudeers](https://claudeers.com/api/badge/claude-mini-hud.svg)](https://claudeers.com/claude-mini-hud)

// retro hit counter

claude-mini-hud hit counter
[![Hits](https://claudeers.com/api/counter/claude-mini-hud.svg)](https://claudeers.com/claude-mini-hud)

// reviews

// guestbook

0/500

// related in Developer Tools

🔓

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Curs…

// devtoolsaffaan-m/JavaScript225,699MIT[ claude ]
🔓

Use Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA

// devtoolsgarrytan/TypeScript119,234MIT[ claude ]
🔓

AI coding assistant skill (Claude Code, Codex, OpenCode, Cursor, Gemini CLI, and more). Turn any folder of code, SQL schemas, R scripts, shell scripts, docs,…

// devtoolssafishamsi/Python80,484MIT[ claude ]
🔓

🙌 OpenHands: AI-Driven Development

// devtoolsOpenHands/Python79,324NOASSERTION[ claude ]
→ see how claude-mini-hud connects across the ecosystem