claude-statusbar — Claude Code 用量监控条：5h/7d 速率上限、上下文窗口、prompt-cache 倒计时

技能简介

Claude Code 默认只在状态行显示极简信息，开发者很难判断「剩余额度多少、何时重置、prompt-cache 还热不热」。claude-statusbar 把这些数字浓缩成终端底部一行（Claude Code statusLine）或桌面悬浮 HUD（macOS），包含 5 小时 / 7 天速率上限条、reset 倒计时、当前模型、上下文占用、prompt-cache 倒计时、可选的本会话成本与账户余额。v3.46.0 引入 Fast Mode（native cache reader + 两个持久化 render worker），显示帧率稳定在 1 秒 / 次。提供 macOS arm64 / Linux x86_64 预编译二进制，零 Python 依赖，一行 curl | bash 即可安装。

核心能力

• 官方 5h / 7d 用量：与 Claude Code 服务端速率限制完全一致，含 reset 倒计时和 end-of-window 投影（→NN%）
• 模型 + 上下文窗口：实时显示当前模型（如 Opus 4.8）和上下文占用（如 350k/1M）
• Prompt-cache 倒计时：显示 cache 剩余热度（如 cache 4m23s），提示下一轮是否吃满 input token 价格
• 成本与余额：可选本会话累计成本，relay / 无额度模式可显示 API 余额
• 两种 UI 形态：Claude Code 状态行内嵌 + macOS 桌面悬浮 HUD（always-on-top）
• 3 种样式 × 9 种主题：battery-bar / capsule / hairline 一键切换主题
• Fast Mode：native cache reader + 两个 render worker，git / 网络采集走独立限流后台队列
• 可观测扩展：git 分支 / diff 统计、会话活跃度、IELTS 写作教练进度，按需开启
• 零依赖安装：预编译单文件二进制，无需 Python；或 pip install 走 Python 客户端
• 自动更新：内置 auto-updater，工具自身保持最新

安装配置

# macOS arm64 / Linux x86_64：单行一键安装（无需 Python）
curl -fsSL https://raw.githubusercontent.com/leeguooooo/claude-code-usage-bar/main/install.sh | bash

# Windows PowerShell（自动安装 uv，无需管理员）
irm https://raw.githubusercontent.com/leeguooooo/claude-code-usage-bar/main/install.ps1 | iex

# 或 pip 安装
pip install claude-statusbar

配置文件 ~/.claude-statusbar/config.toml，支持主题 / 样式 / 扩展模块开关。cs render 命令可在 CI 中独立渲染当前用量快照。

使用步骤

1. 执行安装脚本（macOS / Linux 一行 curl，Windows 一行 irm）
2. 重启 Claude Code 让其读取 statusLine 配置
3. 在终端底部即可看到 5h/7d 速率条 + reset 倒计时
4. macOS 用户额外获得桌面悬浮 HUD（always-on-top）
5. 用 cs config set show_per_model true 开启按模型的周限额细目（需 OAuth 读权限）
6. 用 cs theme capsule / cs theme battery / cs theme hairline 切换样式

适用场景

• 重度 Claude Code 用户：实时跟踪 5h/7d 速率上限避免断流
• 团队 lead：观察团队成员的总体用量，控制 API 预算
• 跨设备开发：macOS 桌面 HUD 让你在 IDE / 终端 / 浏览器切换时也能看到用量
• CI / 批处理场景：在长跑任务中监控消耗，避免半夜 token 耗尽
• prompt-cache 优化：观察 cache 热度倒计时，决定何时主动刷新缓存
• 模型成本归因：开启 per-model 限额看清 Opus / Sonnet / Haiku 的真实占比

适用人群

• Claude Code 高频使用者：开发者、研究员、AI 工程师
• 团队技术管理者：需要分配 Claude API 预算
• 个人付费用户：避免月末意外超额
• 多设备 / 多 IDE 用户：跨设备用量可视化
• DevOps 工程师：在 CI 流水线中嵌入用量报告

工作原理

claude-statusbar 是 Claude Code 的 statusLine 适配器 + 独立可视化层。数据采集层面：countdown / elapsed 从本地时间戳实时计算；context / model / session cost 从 statusLine input 读取；transcript activity 用 bounded tail-byte 增量读取，仅在截断 / 替换时全量重建；git dirty / ahead / behind 用 per-worktree 30 秒缓存 + 单飞刷新；balance / per-model limits 走后台 OAuth 接口（5 分钟缓存）。渲染层面：Fast Mode 用 Go 写的 native cache reader + 两个持久化 render worker，git / 网络采集走独立限流后台队列避免阻塞主渲染循环。Display tick 保持 1 秒，数据采集按各自 schedule 异步刷新。macOS onefile 构建在 v3.32.5 之后切换为 onedir 避免每次刷新留下 ~11 MB 的 _MEI* 临时目录。

官方链接

• PyPI：https://pypi.org/project/claude-statusbar/
• GitHub：https://github.com/leeguellowo/claude-code-usage-bar
• 安装文档：https://github.com/leeguellowo/claude-code-usage-bar/blob/main/docs/install.md
• CI 状态：https://github.com/leeguellowo/claude-code-usage-bar/actions/workflows/ci.yml
• v3.32.5+ 安全更新说明：onedir 模式清理旧 _MEI* 目录
• License：MIT