📊 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	(未设)

Provider 凭据变量

只有需要显示“用量/余额”行时才需要配置。除 Claude 原生 rate_limits 外，平台识别都依赖 ANTHROPIC_BASE_URL；使用第三方代理时通常再配合 ANTHROPIC_AUTH_TOKEN，使用原生平台凭据时则配置下表中的对应变量。

平台	变量	说明
通用代理	ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN	自动检测 provider，并在支持的平台复用代理 token 查询用量
MiniMax	ANTHROPIC_AUTH_TOKEN	Coding Plan 用量接口走代理 token，平台由 ANTHROPIC_BASE_URL 自动识别
DeepSeek	DEEPSEEK_API_KEY	未设置时回退 ANTHROPIC_AUTH_TOKEN
Kimi / Moonshot	MOONSHOT_API_KEY	未设置时回退 ANTHROPIC_AUTH_TOKEN
Kimi For Coding	ANTHROPIC_AUTH_TOKEN	Coding 用量接口使用当前代理 token
智谱 GLM	ZHIPUAI_API_KEY / GLM_API_KEY	未设置时回退 ANTHROPIC_AUTH_TOKEN
小米 MiMo	XIAOMI_COOKIE	Cookie 认证，从浏览器 DevTools 复制；XIAOMI_API_KEY / MIMO_API_KEY 仅作兼容兜底
阿里 DashScope	ALIYUN_AK_ID + ALIYUN_AK_SECRET	通过阿里云 BSS OpenAPI 查询账户余额，非 DASHSCOPE_API_KEY
火山引擎 Ark	—	当前仅平台识别，管控面用量 API 暂未集成
阶跃星辰 StepFun	STEPFUN_API_KEY	未设置时回退 ANTHROPIC_AUTH_TOKEN
硅基流动 SiliconFlow	SILICONFLOW_API_KEY	未设置时回退 ANTHROPIC_AUTH_TOKEN

在 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.1/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.1\\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%	▒ 运行中 █ 已完成
复古终端

💡 自由组合: 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=1	renderModelLine
$ 花费	累计 $ + 耗时 + $/h 增速	SHOW_COST=1	renderCostLine
⎇ 分支	分支名 + dirty/干净 + ahead/behind	SHOW_GIT=1	renderGitLine
⚠ 告警	上下文/用量阈值提醒	默认开 (WARN=0 关)	renderAlertLine

Token 行字段详解

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

字段	来源	用途
入 / in	total_input_tokens (stdin) 或 transcript 累加	本次会话累计输入 token
出 / out	total_output_tokens (stdin) 或 transcript 累加	本次会话累计输出 token
缓存 / cache	cache_creation_input_tokens + cache_read_input_tokens	prompt 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 标签	触发条件
Bedrock	CLAUDE_CODE_USE_BEDROCK=1
Vertex	CLAUDE_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/gradient/shades/retro/ascii/rail/star/spark/heart/love

或自定义主题,修改 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.ts 的 main() 里注册到 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.1/dist/index.js

# 2. 手动测试,看 stdout 有没有内容
echo '{"model":{"display_name":"test"}}' | node ~/.claude/plugins/cache/local/claude-mini-hud/1.2.1/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.json 里 transcriptPath (在 claude config 内部,不是 statusLine) 是否可读。

Q: 中文显示乱码

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

locale   # 应含 UTF-8
echo $LANG

如果是 POSIX 或 C,改成:

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: 推荐按下面顺序选一种:

方式 1: 让 AI 帮你升级

把下面这段复制给 Claude Code / Codex / Cursor:

请帮我把已安装的 claude-mini-hud 插件升级到最新版本。

要求:
1. 如果当前环境支持 Claude Code 插件命令,请优先通过插件市场更新:
   /plugin marketplace add zander-zyx/claude-mini-hud
   /plugin install claude-mini-hud
   /reload-plugins
2. 如果你不能直接执行 Claude Code 插件命令,请明确告诉我复制上面的 3 条命令到 Claude Code 里执行。
3. 不要删除、覆盖或重置我的 Claude Code 配置文件。
4. 操作前先说明你准备执行的命令。
5. 完成后提醒我重启 Claude Code 生效。
6. 只有插件市场方式不可用时,才考虑源码方式。

方式 2: 通过 Claude Code 插件市场更新

/plugin marketplace add zander-zyx/claude-mini-hud
/plugin install claude-mini-hud
/reload-plugins

方式 3: 拉取源码更新

macOS / Linux:

git clone https://github.com/zander-zyx/claude-mini-hud.git
cd claude-mini-hud
npm install && npm run build

Windows PowerShell:

git clone https://github.com/zander-zyx/claude-mini-hud.git
cd claude-mini-hud
npm install; npm run build

然后把 statusLine.command 指向该目录下的 dist/index.js,升级后重启 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 + 跑 57 个测试 (用 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

测试覆盖 (57 个用例)

#	用例	验证
1–3	CLI / 版本 / 非阻塞刷新	基础输出、--version、主进程不等待 HTTP
4–9	可选模型 / fallback / 颜色 / 主题	环境变量与渲染回归
10–15	Context / Token / Todo / provider	数值与 transcript 回归
16–18	语言模式	zh/en/minimal 输出验证
19–38	多平台检测	URL 匹配 (含国际站)
39–57	缓存、凭据、后台锁、余额解析与端到端	见 tests/usage.test.ts

项目结构

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       # 进度条主题系统 (21 种可选)
│   ├── 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 - v1.2.1):

• 进度条主题系统 (21 种风格: 经典/霓虹/点阵/硬核/简约/像素/钻石/箭头/波浪/潮汐/圆点/靶心/渐变/阴影/复古/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) + 单行紧凑模式 (CLAUDE_MINI_HUD_COMPACT=1)
• 多窗口切换时更平滑的刷新 (按 transcript_path 隔离缓存)
• 从环境变量读取颜色阈值 (CLAUDE_MINI_HUD_RED_PCT / CLAUDE_MINI_HUD_YELLOW_PCT)
• 可点击的状态栏链接 (OSC 8 链接跳转到当前 transcript, 取决于终端支持)
• 大 transcript Todo 状态追踪修复 (早期/中段 TaskCreate 能匹配尾部 TaskUpdate)
• CLI 版本输出 (claude-mini-hud --version)

后续计划:

• 亮色/暗色主题适配 (如果 Claude Code/TUI 暴露可检测的主题信息)
• 鼠标悬停提示 (受 Claude Code TUI 限制, 目前状态栏不提供 hover 能力)
• 更多平台用量 API 适配 (优先接入有公开余额/用量接口的平台)
• 更细粒度的阈值配置 (Context / Usage / 月度用量分开配置)

---

相关项目

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

---

License

MIT © 2026 Zander Zhang — 详见 LICENSE

---

致谢

• 灵感来自 jarrodwatts/claude-hud
• 用 Claude Code / Codex / ZCode 一起写这个项目(自举!)
• 感谢所有 contributors

---

Star History

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

---

English

See README.en.md.