claude-hud

🎨 Claude HUD - 让你的 AI 编程更有范儿

一个超酷的 Claude Code 状态栏插件，把终端底部变成赛博朋克风格的 HUD 界面！

---

🤔 为什么要做这个？

你是否遇到过这些问题：

• 😵 上下文爆了都不知道 —— 写着写着突然发现 token 用完了
• 🎨 默认界面太丑 —— 绿黄红的"交通灯"配色看着就烦
• 📊 信息太分散 —— 想看个进度条还得翻半天

于是，我们基于 Jarrod Watts 的原项目 重新设计了整套配色和视觉，并加了一键安装命令。

---

✨ 核心特性

💙 全蓝色美学配色

告别红黄绿，拥抱赛博蓝。上下文使用率用蓝色系深浅渐变表达风险：

 0% ▱▱▱▱▱▱▱▱▱▱  青色   😎 轻松愉快
30% ▰▰▰▱▱▱▱▱▱▱  青色   👌 状态良好
70% ▰▰▰▰▰▰▰▱▱▱  亮蓝   ⚠️  开始警告
85% ▰▰▰▰▰▰▰▰▱▱  天蓝   🔥 高度警告
95% ▰▰▰▰▰▰▰▰▰▱  深蓝   💀 即将爆炸

统一的蓝色系，渐进式警告，让你提前感知风险而不是突然爆炸。

▰▱ 现代化进度条 + 清晰分隔

使用 Unicode 字符 ▰ ▱ 打造精致进度条，用 ┃ 分隔信息层次：

[Opus 4.5] ▰▰▰▰▰▰▰▰▱▱ 82% ┃ my-app ┃ git:(dev*) ┃ 5h: 45%

🌍 全模型上下文监控 —— 不只是 Claude

内置智能推断系统，自动识别模型上下文窗口大小，第三方/代理模型也能精准显示进度条：

• ✅ Claude 全系列 —— Opus / Sonnet / Haiku，4.x 与 3.x
• ✅ OpenAI GPT —— GPT-5.x、GPT-4o
• ✅ DeepSeek / Kimi —— V4/V3/V2.5、K2.x 自动识别
• ✅ Bedrock / Vertex / 企业版 —— 云平台与企业别名无缝对接
• ✅ 自定义模型 —— 正则匹配，想加啥加啥

---

🎮 快速开始

1. 构建

npm ci
npm run build

2. 一键注册状态栏（推荐）

在 Claude Code 里直接运行斜杠命令：

/claude-hud:setup

它会自动把状态栏命令以绝对路径写进你的 settings.json（写前自动备份 .bak，幂等可重复运行，遇到你自己配的状态栏会先询问）。

💡 为什么需要这一步？Claude Code 的状态栏只能在 settings.json 里配置，插件清单（plugin.json）不支持声明状态栏，而且状态栏命令不会展开 ${CLAUDE_PLUGIN_ROOT}，所以必须写绝对路径。/claude-hud:setup 帮你自动搞定。

3. 重启会话

新开一个 Claude Code 会话，状态栏只在会话启动时读取一次，当前会话看不到效果。

---

🎛️ 配置

配置文件位于 ~/.claude/plugins/claude-hud/config.json（若设置了 CLAUDE_CONFIG_DIR 则跟随该目录）。

{
  "lineLayout": "compact",
  "colors": {
    "context": "cyan",
    "usage": "brightBlue",
    "model": "brightBlue",
    "project": "cyan",
    "git": "brightBlue",
    "gitBranch": "cyan"
  }
}

布局模式

{ "lineLayout": "compact" }   // 紧凑单行（推荐）
{ "lineLayout": "expanded" }  // 展开多行

语言

{ "language": "zh" }   // 简体中文
{ "language": "en" }   // English

自定义颜色

颜色支持三种写法：命名色（cyan、brightBlue 等）、256 色索引（0-255）、十六进制（#5fafff）。

{
  "colors": {
    "context": "cyan",        // 青色（低使用率）
    "usage": "brightBlue",    // 亮蓝色（正常使用率）
    "usageWarning": 117,      // 天蓝色（256 色）
    "critical": 27,           // 深蓝色（256 色）
    "model": "brightBlue",
    "project": "cyan",
    "git": "brightBlue",
    "gitBranch": "cyan",
    "label": "dim"            // 暗淡（标签）
  }
}

---

🌍 第三方模型支持

用 Bedrock 接 Claude、接 DeepSeek/Kimi、或自建网关时，模型可能不上报上下文窗口大小，导致进度条不准。HUD 内置一套五层智能推断机制解决这个问题。

⚡ 五层优先级

HUD 按以下优先级推断上下文窗口大小，越靠前越优先：

1️⃣ 模型专属覆盖      contextWindowSizeOverridesByModel（最精确）
2️⃣ 全局覆盖          contextWindowSizeOverride（一刀切）
3️⃣ Claude Code 原生  stdin 上报的官方值
4️⃣ 自定义正则        customModelMappings（你的规则）
5️⃣ 内置模型库        开箱即用的兜底表

三种配置方式

方式一：模型专属覆盖（推荐） —— 按 id 或 display_name 精确匹配

{
  "display": {
    "contextWindowSizeOverridesByModel": {
      "claude-sonnet-4-5": 1000000,
      "gpt-4o": 128000,
      "deepseek-chat": 65000
    }
  }
}

方式二：全局覆盖 —— 所有模型用同一个值，适合单模型场景

{ "display": { "contextWindowSizeOverride": 200000 } }

方式三：正则匹配 —— 一条规则匹配一批模型

{
  "display": {
    "customModelMappings": [
      { "pattern": "deepseek.*v4", "contextWindowSize": 1000000, "comment": "DeepSeek V4 系列" },
      { "pattern": "kimi.*k2",     "contextWindowSize": 256000,  "comment": "Kimi K2 系列" }
    ]
  }
}

📌 归一化规则：匹配前模型名会被归一化 —— 转小写、分隔符（.、-、_、@、:）转空格、去掉 Claude 前缀、移除括号内容。例如 "Claude Sonnet 4.5" → "sonnet 4 5"。正则请针对归一化后的形式书写，且不区分大小写。

📚 内置模型库（开箱即用，无需配置）

模型系列	上下文大小	匹配规则
Claude Opus 4.x	1M	opus 4
Claude Sonnet 4.x	1M	sonnet 4
Claude Haiku 4.x	200K	haiku 4
Claude Sonnet 3.7	200K	sonnet 3 7
Claude 3.5 Sonnet	200K	3 5 sonnet
Claude 3.5 Haiku	200K	3 5 haiku
企业版 Opus / Sonnet	1M	opusplan / sonnetplan
企业版 Haiku	200K	haikuplan
GPT-5.5 / GPT-5.4	400K	gpt 5 5 / gpt 5 4
GPT-4o	128K	gpt 4o
DeepSeek V4	1M	deepseek v4
DeepSeek V3	65K	deepseek v3
DeepSeek V2.5	64K	deepseek v2 5
Kimi K2.6 / K2.5	256K	kimi k2 6 / kimi k2 5

如果你的模型在表里，啥都不用配，直接用。

---

🐛 调试技巧

开启调试模式，查看上下文大小来源：

# Windows PowerShell
$env:DEBUG = "claude-hud"

# Linux / macOS
export DEBUG=claude-hud

HUD 会在 stderr 输出诊断信息（不会污染状态栏）：

[claude-hud:context] resolved context window size 1000000 from custom_mappings

可能的来源：model_override / global_override / stdin / custom_mappings / model_map。

---

📊 技术特性

• ✅ TypeScript 编写，类型安全
• ✅ 运行时零依赖，启动飞快
• ✅ 正则缓存 + 转写缓存，状态栏每 ~300ms 刷新也不卡
• ✅ ANSI / Unicode / CJK 宽度感知，对齐精准
• ✅ 中英双语，模块化设计

---

📬 联系我

• 👤 维护者：kelong (Zhaxideler)
• 📧 邮箱：[email protected]
• 💬 反馈：欢迎通过邮件或 GitHub Issues 交流

不管是 Bug 报告、功能建议，还是想聊聊 AI 编程的心得，随时欢迎！

---

🤝 贡献