CodeBuddy HUD

CodeBuddy HUD 是一个面向 CodeBuddy Code statusLine 的多行终端 HUD，灵感来自 claude-hud 的终端信息面板体验。

它作为 CodeBuddy 原生 statusLine.command 运行，从 stdin 读取 CodeBuddy 传入的 JSON，按需解析本地会话 transcript，并直接在终端底部渲染紧凑的多行状态面板。

CodeBuddy · GPT-5.5 · live-iOS · git release/3.43.0 *
上下文 █░░░░░░░░░░░░░░░ 9.2% · 词元 91.7K/1M · 缓存 5.8M
词元 输入 715.9K · 输出 22.9K · 变更 +168 -1

展示内容

| 区域 | 数据来源 | 示例 | | --- | --- | --- | | 模型和项目 | CodeBuddy statusLine JSON | GPT-5.5 · live-iOS | | Git 状态 | 本地 git 命令 | git main * | | 上下文占用 | context_window.* | 91.7K/1M · 9.2% | | Cache token | current_usage.cache_* | cache 5.8M | | 词元总量 | total_input_tokens, total_output_tokens | 输入 715.9K · 输出 22.9K | | 代码变更 | cost.total_lines_* | 变更 +168 -1，显示在词元总量同一行 | | 积分/配额 | 官方字段、快照或 transcript 估算 | 默认隐藏，可配置开启 |

环境要求

• 支持 statusLine.command 的 CodeBuddy Code
• Node.js >=18.0.0
• 如果要显示分支/dirty 状态，需要安装 Git
• 无生产 npm 依赖

快速部署

推荐安装到 CodeBuddy 插件目录：

git clone https://github.com/xiaogehenjimo/codebuddy-hud.git ~/.codebuddy/plugins/codebuddy-hud

启用 HUD：

node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js setup

setup 会更新 ~/.codebuddy/settings.json：

{
  "statusLine": {
    "type": "command",
    "command": "node /Users/you/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js status"
  }
}

同时会把旧的 statusLine 保存到 .meta.json，方便后续回滚。

通过 npm 安装

如果已发布到 npm，也可以使用：

npm install -g codebuddy-hud

然后运行：

codebuddy-hud setup

如果你不想全局安装，也可以在仓库目录中直接使用 Node：

node bin/codebuddy-hud.js setup

常用命令

codebuddy-hud status       # 从 stdin JSON 渲染 HUD
codebuddy-hud inspect      # 查看 statusLine JSON 字段
codebuddy-hud setup        # 写入 ~/.codebuddy/settings.json
codebuddy-hud uninstall    # 恢复之前的 statusLine
codebuddy-hud config-path  # 输出当前配置路径
codebuddy-hud configure    # 管理 HUD 配置

如果未全局安装：

node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js status

配置

首次运行会在插件目录生成 config.json。仓库内提供干净模板 config.example.json。

CodeBuddy statusLine 的可见行数主要受 CodeBuddy UI 约束，不是 Ghostty 或 shell 决定。如果你的 CodeBuddy 终端只显示一两行，可以把 maxLines 调低，并把最重要的信息放在前面。插件默认输出 4 行：

查看配置：

node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js configure list

读取单个配置：

node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js configure get display.showCredits

修改配置：

node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js configure set maxLines 4
node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js configure set barWidth 20

切换语言：

node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js configure set language zh
node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js configure set language en

积分/配额默认不展示。需要先开启显示开关，再配置数据来源：

node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js configure set display.showCredits true
node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js configure set credits.enabled true
node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js configure set credits.totalCredits 500
node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js configure set credits.usedCreditsOffset 0

没有官方字段时的计算方式：

剩余积分 = 总积分 - 历史已用偏移 - 本地 transcript 统计积分

如果未来 CodeBuddy 在 statusLine JSON 中提供官方积分/账单字段，HUD 会优先读取，例如 credits.remaining_credits、credits.total_credits、billing.remainingCredits、billing.totalCredits、plan.* 或 quota.*。

如果官方字段不存在，HUD 可以读取你显式配置的本地配额快照：

node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js configure set credits.snapshotPath ~/.codebuddy/quota.json
node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js configure set credits.maxStalenessMs 3600000
node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js configure set credits.refreshCommand '你信任的、会写入 ~/.codebuddy/quota.json 的命令'
node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js quota refresh
node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js quota status

快照示例：

{
  "quota": {
    "remaining": 75,
    "used": 25,
    "total": 100,
    "plan": "Pro",
    "resetAt": "2026-06-01T00:00:00Z",
    "updatedAt": "2026-05-10T06:00:00Z"
  }
}

如果官方字段和快照都不存在，则回退到本地 transcript 估算。本地估算不是官方账号余额。其它机器、其它项目或已清理 transcript 的消耗可能无法统计。HUD 在 status 渲染期间不会读取凭据，也不会调用未文档化的 API。refreshCommand 只会在你显式执行 quota refresh 时运行。

language 只影响 HUD 标签和命令行提示，不会翻译模型名、分支名、工具名或 token 单位。

切换布尔开关：

node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js configure toggle display.showCredits

应用预设：

node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js configure preset minimal
node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js configure preset default
node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js configure preset full

常用显示开关：

| 配置项 | 默认值 | 说明 | | --- | --- | --- | | display.showContext | true | 显示上下文占用行 | | display.showTokens | true | 显示输入/输出 token 总量 | | display.showCache | true | 显示 prompt/cache token | | display.showCost | false | 显示 CodeBuddy 提供的 USD 成本 | | display.showCredits | false | 显示官方字段、快照或 transcript 估算得到的积分/配额 | | display.showLinesChanged | true | 在词元总量同一行显示代码变更 | | colors.enabled | true | 是否启用 ANSI 颜色 |

上下文阈值

{
  "thresholds": {
    "contextWarning": 70,
    "contextDanger": 90
  }
}

上下文进度条会根据阈值显示正常、警告、危险颜色。

工作原理

CodeBuddy Code
  -> 通过 stdin 传入 statusLine JSON
  -> codebuddy-hud status
  -> 可选解析 transcript JSONL
  -> 查询 git 状态
  -> 输出 ANSI 多行 HUD

设计原则：

• transcript 解析失败不会影响基础 HUD 渲染。
• 没有 transcript 时会自动退化为 stdin-only 显示。
• 不依赖外部生产 npm 包。
• 本地运行状态不会提交到 git：.cache.json、.meta.json、config.json 都会被忽略。

验证部署

使用测试 fixture：

npm run build
npm test
npm run test:stdin

使用真实 CodeBuddy statusLine JSON：

node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js status < ~/.codebuddy/statusline-last-input.json

查看 CodeBuddy 实际传入字段：

node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js inspect < ~/.codebuddy/statusline-last-input.json

回滚

自动回滚到安装前的 statusLine：

node ~/.codebuddy/plugins/codebuddy-hud/bin/codebuddy-hud.js uninstall

手动回滚示例：

{
  "statusLine": {
    "type": "command",
    "command": "/bin/sh /Users/you/.codebuddy/statusline-ys.sh"
  }
}

致谢

本项目受到 jarrodwatts/claude-hud 的终端 HUD 思路和仓库组织风格启发，但这是一个独立的 CodeBuddy Code 实现。

License

Apache-2.0. See LICENSE.