CodexBar

背景故事：你的 AI 额度正在悄悄耗尽

你在深夜写代码，调取 Claude 的 long-thinking 模式处理一个复杂的重构任务。突然弹窗：「本次对话额度已用尽，请升级订阅。」

这不是你的错——AI 编程工具的用量追踪极度不透明：各平台（OpenAI Codex、Claude Code、Cursor、Grok 等）的用量窗口各不相同，Session 限额、每周限额、每月限额散落在不同后台，而且刷新时机也不一致。「我到底还能用多久？」这个简单的问题，长期没有好的答案。

CodexBar 正是为解决这个问题而生——它是一个运行在 macOS 菜单栏的小工具，通过抓取各平台 API 调用数据、使用额度、费用记录，将所有 AI 编程工具的用量状态集中展示在屏幕顶部的一小块菜单栏区域，让你在写代码的同时，随时掌握自己的额度余量和重置时间。## 项目起源与作者背景

CodexBar 由独立开发者 steipete（Peter Steinberger）开发维护。steipete 是 iOS/macOS 开发领域知名的独立开发者，曾创办 PSPDFKit（一个久负盛名的 PDF SDK），在 GitHub 上长期活跃，CodexBar 项目获得了超过 17,000 颗星，是 AI 编程辅助工具生态中难得的、专注于「工具效率可视化」的开源项目。

项目的设计哲学在 VISION.md 中有清晰阐述：优先做性能改进和小幅功能迭代，新功能和大改版需要审批，任何涉及用户隐私的改动（认证数据、存储、发布）都需要 sign-off，体现了作者对隐私保护的高度重视。## 核心功能：57+ AI 编程平台的用量仪表盘

CodexBar 支持的 AI 编程平台极为广泛，覆盖以下类别：

OpenAI 生态：Codex（原生）、OpenAI API（Admin Key 用量/费用图）、 Anthropic 生态：Claude（OAuth API、浏览器 Cookie、CLI PTY 多方式抓取）、 Cursor 生态：Cursor（浏览器会话 Cookie 读取计划+用量+账单重置）、 其他主流平台：Gemini、Copilot、Grok、GroqCloud、Deepgram、Zed、Warp、JetBrains AI、 国内平台：Kimi（Token 计划）、Kimi K2、StepFun（阶跃星辰）、MiniMax、阿里云编程计划、 聚合平台：OpenRouter、LiteLLM、LLM Proxy、AWS Bedrock、Augment、Devin、Venice 等。

每个平台的用量数据展示方式包括：

1. 使用量条（Usage Bar）：直观显示当前用量占限额的百分比
2. 重置倒计时（Reset Countdown）：精确到分钟的下一个窗口重置时间
3. 费用/消费记录（Cost History）：本地扫描日志或从平台账单 API 获取历史消费曲线
4. 平台状态指示（Status Badge）：当平台出现故障时，菜单栏图标上叠加告警徽章
5. Credits 余额：对支持查询的平台，直接显示账户余额## 技术架构：模块化的提供者驱动设计

CodexBar 的代码架构清晰分为以下核心模块：

模块	职责
CodexBarCore	数据获取与解析：Codex RPC 调用、PTY 运行器、Claude 探针、OpenAI 网页抓取、状态轮询
CodexBar	状态管理与 UI：UsageStore、SettingsStore、StatusItemController、菜单渲染、图标绘制
CodexBarWidget	WidgetKit 扩展，读取共享快照在通知中心和桌面小部件展示
CodexBarCLI	命令行工具，提供 codexbar 命令查询用量/状态
CodexBarClaudeWatchdog	Claude CLI PTY 会话稳定性守护进程
CodexBarClaudeWebProbe	Claude Web 抓取诊断 CLI 辅助工具

提供者驱动架构（Provider-Driven Architecture）

这是 CodexBar 架构最值得称道的部分。作者设计了一套 Descriptor-Driven 的提供者框架：

每个 AI 平台对应一个 ProviderDescriptor（描述符）和一组 ProviderFetchStrategy（抓取策略）。描述符是标签、URL、默认启用的单一真相来源；抓取策略则实现具体的数据获取路径（CLI 调用、Web Cookie、OAuth API 等）。

这种设计的核心优势在于：新增一个平台支持，不需要改动 UI 代码，只需要定义一个描述符 + 实现抓取策略，UI 完全由描述符驱动自动渲染，这使得 CodexBar 能在短时间内支持 57+ 平台而不会陷入「特殊逻辑蔓延」的泥沼。

数据流

后台刷新 → UsageFetcher/提供者探针 → UsageStore → 菜单栏/图标/Widget

整个数据流是单向的，状态存储（UsageStore）与 UI 层（CodexBar）完全解耦，Widget 通过读取同一个共享快照数据，实现通知中心和桌面小部件的实时同步。

隐私优先设计

CodexBar 的隐私设计非常克制：不存储任何密码，复用平台现有的认证方式（OAuth、设备流、API Key、浏览器 Cookie、本地文件），所有数据处理在本地完成，没有上报服务器，体现了「隐私优先」的设计承诺。## 关键技术选型

Swift 6 + 严格并发：整个项目启用 Swift 6 的 Strict Concurrency 模式，强制所有状态符合 Sendable 协议，并显式标注 MainActor 边界，这是 Apple 平台最新的安全并发实践，在开源项目中相当罕见。

SwiftUI + AppKit 混合：菜单栏 UI 基于 SwiftUI，但底层需要调用 AppKit 的 NSStatusItem，两者混合使用是 macOS 14+ 应用的常见模式。

Sparkle：内置 Sparkle 自动更新框架，用户无需手动检查更新。

Swift-Crypto：处理 HTTPS 通信和敏感数据的加密。

SQLite3：Linux 版本通过系统库 SQLite3 持久化用量历史数据。

Vortex（自定义图形库）：用于图标渲染和动态 UI 效果。

SweetCookieKit（steipete 自有库）：跨浏览器 Cookie 导入，支持 Safari/Chrome/Firefox。## 上手体验

CodexBar 安装后没有任何 Dock 图标，仅在屏幕顶部的菜单栏区域显示一个小图标，点击即可展开用量面板。这种「零存在感」的 UI 设计是菜单栏应用的精髓——不打扰用户，只在需要时呈现关键信息。

首次启动需要在设置中添加使用的平台（支持 API Key、浏览器会话、CLI 工具等多种认证方式），配置完成后，菜单栏图标会根据用量情况动态变化（颜色、图标形状）。

CLI 版本（codexbar）同样强大，支持 codexbar config providers、codexbar config enable --provider 等命令，可以在脚本中自动化平台配置，运维人员友好。## 局限与争议

1. 平台依赖性：CodexBar 的数据来源依赖各平台公开/半公开的接口，一旦平台修改了网页结构或 API 响应格式，对应的抓取策略就会失效，需要及时更新。

2. macOS 独占：主应用仅支持 macOS 14+，Linux 版本仅有 CLI 工具，Windows 用户目前无法使用图形界面版本。

3. Cookie 管理复杂性：部分平台依赖浏览器 Cookie 导入，需要用户手动授权浏览器扩展访问，对隐私敏感的用户可能存在一定门槛。## 行业意义

CodexBar 的出现折射了一个趋势：随着 AI 编程工具的普及，用户对「用量可视化」的需求正在快速增长。从 Copilot 的用量仪表盘、Cursor 的使用统计到 Claude 的 API 后台，各平台的用量信息分散且不统一，CodexBar 通过聚合展示填补了这个空白。

从工程角度看，CodexBar 的 Descriptor-Driven Provider 架构也为类似「多源数据聚合」场景提供了一个优雅的参考设计：用描述符驱动 UI，用策略模式实现数据获取，用严格的并发模型保证稳定性，这些实践对任何需要接入多个外部 API 的项目都有参考价值。

项目保持了活跃的开发节奏，GitHub 更新频繁，支持平台持续增加，对于重度使用 AI 编程工具的开发者而言，CodexBar 已经是不可或缺的效率伴侣。

---

图1：CodexBar 费用历史图表（cost-chart）

图2：作者 steipete（Peter Steinberger）