claude-mini-hud

📊 claude-mini-hud

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

21 种进度条主题 · 4 种显示模式 · 零运行时依赖 · 用量查询后台刷新

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

---

这是什么?

claude-mini-hud 是一个 Claude Code StatusLine 插件,在你的输入框下方持续显示会话的关键指标。默认显示 Context + Token 两行，并按数据和配置追加条件行。对标 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 三种可切换
• 🚀 非阻塞用量刷新: 缓存未命中时由独立后台进程查询，不等待供应商 HTTP 接口
• 🔌 即插即用: /claude-mini-hud:setup 一条命令

多平台用量/余额查询

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

平台	检测条件	显示格式
Claude 原生	rate_limits 有数据	5h:45% (1h30m) 7d:12%
MiniMax	URL 含 minimaxi.com (国内) / minimax.io (国际)	5h:55% 7d:74% m:50% (26d)
智谱 (GLM)	URL 含 bigmodel.cn / z.ai	5h:21% (1h54m) 7d:26% m:30% (26d) mcp:20/1000
小米 (MiMo)	URL 含 xiaomimimo	50M/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	平台识别 (包月订阅)
DeepSeek	URL 含 deepseek.com	¥123.45 (账户余额)
Kimi	URL 含 moonshot.cn / moonshot.ai	¥42.50 (赠送 ¥10.00)
Kimi For Coding	URL 含 api.kimi.com/coding	5h: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_URL 和 ANTHROPIC_AUTH_TOKEN，插件会自动识别平台并优先复用代理 token 查询。

🔐 原生凭据：保留对应平台的 ANTHROPIC_BASE_URL 用于识别，再设置下方“Provider 凭据变量”。其中小米 MiMo 使用 Cookie 认证；阿里 DashScope 余额走阿里云 BSS OpenAPI，不是 DASHSCOPE_API_KEY。

与 claude-hud 的定位

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

1. 对标 claude-hud 核心功能 — 支持工具活动、Agent 追踪、Task 解析等能力，默认布局保持 Context + Token 两条基础行
2. 深度适配国产大模型 — 内置智谱 GLM、MiniMax、小米 MiMo、阿里 DashScope、DeepSeek、Kimi、Kimi For Coding、阶跃星辰 StepFun、硅基流动 SiliconFlow 的用量/余额查询；火山引擎、百度千帆、腾讯混元、讯飞星辰目前仅做平台识别

---

📑 目录

• 前置条件
• 30 秒快速体验
• 安装
  • 方式 0: 让 Claude 自己装 (最省心)
  • 方式 1: Marketplace (推荐)
  • 方式 2: 手动 git clone
  • 方式 3: Windows PowerShell
  • Linux tmpfs 修复
• 使用
• 配置
  • 环境变量详解
  • 显示字段说明
• 自定义
• FAQ
• 开发
• 贡献
• 相关项目
• License

---

前置条件

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

依赖	最低版本	检查命令	说明
Claude Code CLI	≥ 2.0	claude --version	支持 StatusLine 的最低版本,推荐 ≥ 2.1.6 (百分比更准)。安装文档
Node.js	≥ 18.0.0	node --version	用于编译 TypeScript
npm	≥ 9.0	npm --version	装 TypeScript
TypeScript	≥ 5.4	npx 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. 选择进度条主题 + 工具标记风格 (可选, 21 种主题自由组合, 默认经典)
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.1

# 2. 进入目录编译
cd ~/.claude/plugins/cache/local/claude-mini-hud/1.2.1
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.1/dist/index.js"
  }
}

# 4. 重启 Claude Code

💡 目录命名规范:Claude Code 期望 {vendor}/{name}/{version}/ 三级结构。local 是 vendor,claude-mini-hud 是 name,1.2.1 是 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.1

# 2. 编译
cd $env:USERPROFILE\.claude\plugins\cache\local\claude-mini-hud\1.2.1
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.1\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)

供应商用量查询采用 5 分钟缓存；缓存未命中时由独立后台进程刷新，主 StatusLine 不等待网络响应。

---

配置

环境变量详解

变量	默认	可选值	说明
CLAUDE_MINI_HUD_LANG	zh	zh / en / minimal / ultra-minimal	界面语言 (minimal = 英中混搭 + 无 emoji, ultra-minimal = 只显示 Context + Token 两行)
CLAUDE_MINI_HUD_THEME	default	21 种,见主题预览	进度条风格
CLAUDE_MINI_HUD_MARKS	default	21 种,见主题预览	工具/Agent 标记图标 (独立于进度条, 可自由组合)
CLAUDE_MINI_HUD_SHOW_MODEL	(未设)	1	设置为 1 时显示模型行
ANTHROPIC_MODEL / ANTHROPIC_DEFAULT_OPUS_MODEL / ANTHROPIC_DEFAULT_SONNET_MODEL / ANTHROPIC_DEFAULT_HAIKU_MODEL	(未设)	模型名	代理场景下用于补充模型行和 MiniMax 当前模型匹配
CLAUDE_MINI_HUD_TOKEN_MODE	session	session / context / both	Token 行模式: 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_WARN	1 (开)	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_PCT	80	0-100	红色阈值: 百分比 ≥ 此值显示红色 (Context / 用量窗口 / 月度统一生效)
CLAUDE_MINI_HUD_YELLOW_PCT	60	0-100	黄色阈值: 百分比 ≥ 此值显示黄色, < 红色阈值
CLAUDE_MINI_HUD_BG	(自动)	light / dark	终端背景色, 用于颜色对比度适配。未设时自动读 COLORFGBG / TERM_BACKGROUND_COLOR, 默认 dark
TERM_PROGRAM / LC_TERMINAL	(自动)	终端标识	用于自动判断终端是否可靠支持 emoji；通常无需手动设置
CLAUDE_MINI_HUD_DEBUG	(未设)	1	调试模式: 输出各模块 (usage 查询/缓存) 的错误信息到 stderr, 用于排查"用量行不显示"等问题

Provider 凭据变量