usage：把 AI 配额刻进菜单栏，永远不再被限额打措手不及

想象一个场景：凌晨两点，你正在用 Claude Code 做一场大规模重构——几千行遗留代码等待被模块化，每一个 Ask 都是一场精准的手术。进度条已经走到 82%，然后 Claude Code 发来一条冷冰冰的消息："You've reached your context limit." 你不得不 /clear，重新 paste 背景，重新解释上下文，一切从头来过。

这不是故事，这是真实发生过的噩梦。而 usage 这个开源工具，就是为了让这类噩梦从此绝迹而诞生的。

背景：AI 编程工具的配额焦虑

Claude Code、Codex（OpenAI）和 Antigravity（Google Gemini）是目前最主流的三款 AI 编程工具，它们都采用"按 token 计费"的商业模式。在重度使用场景下，配额消耗速度极快——一个周末的重构工作可能烧掉一整周的额度。

但问题是：这些工具不会主动告诉你还剩多少。你只有两种选择：要么时不时手动去网页查，要么等到额度耗尽被迫中断。

usage 的作者 aqua5230 显然深受其扰——这个项目正是为了解决这个痛点而生的。

核心设计：本地优先，零 API 消耗

usage 最聪明的地方在于它的数据来源策略。Claude Code 和 Codex 的使用数据完全从本机已有的日志文件读取，完全不调用 Anthropic 或 OpenAI 的任何 API。这意味着你可以 24 小时开着它监控配额，而不会因此多花一分钱 token。

Antigravity 稍有不同——它的配额来自 Google 官方接口，但用的也是 Antigravity CLI 已经保存在本机的登录身份，本质上只是一次元数据查询，同样不消耗模型配额。

这种"只读本地日志 + 最小化网络请求"的设计哲学，让 usage 在隐私和成本两方面都做到了极致。开发者社区对此反响热烈，项目上线不久就积累了近 300 颗星，GitHub 上也引发了热烈讨论——许多人表示这正是他们一直寻找但没有的工具。

经典主题面板，绿色到红色配额编码一目了然

功能全景：不止于配额显示

usage 的功能远不止一个"数字显示"。它是一个完整的 AI 使用管理平台：

实时监视与预警：配额以绿→黄→红的颜色编码常驻菜单栏，70% 上下文时主动提醒你 /clear，避免无效 token 浪费。

服务状态监控：自动读取 Claude、Claude API 和 Codex API 的官方状态页，遇到故障时在面板底部显示橘红警示横幅。

进度管家（Session Resume）：当你打开新的 Claude Code 会话时，usage 自动将上次未提交的变更、未完成的待办事项交给 AI，无需手动 /resume。

Token 节省器：菜单栏一键切换"简洁模式"，要求 Claude Code 和 Codex 在当前会话中更精简地回答。A/B 测试显示，对话后期回复平均缩短约 40%。

AI 圆桌讨论：开启一个独立窗口，让 Claude Code、Codex、Antigravity 三方进行多轮辩论，附共识计票和 token 消耗预估。

HTML 深度报告：可导出的离线 HTML 报告，包含日/周 token 趋势、项目排名、费用明细、年度 Wrapped 摘要，甚至有贡献热图。

usage 主面板，展示多主题可选

技术架构：Python + PyObjC 的原生之路

usage 选择 Python 作为主力语言，并通过 PyObjC 深度集成 macOS 原生能力。这不是一个"Electron 包装的 Web 应用"，而是一个真正的 macOS 菜单栏应用——图标响应迅速，动画流畅，系统资源占用极低。

项目采用 modern Python 3.13 + uv 包管理器，代码结构清晰模块化：

• adapters/：对接 Claude Code、Codex、Antigravity 的数据适配层
• analyzer/：日志分析与消耗速率计算
• menubar/：macOS 菜单栏图标与交互
• panels/：浮窗面板 UI 组件
• tui/：纯终端 TUI 版本（uvx usage-cli）
• ui/：通用 UI 组件

支持 10 种视觉主题，包括 Classic、Matrix、Windows 95、Catppuccin（完整 4 款 flavor）、Midnight Aquarium、Prism Arcade 等。每款主题都有配套的菜单栏图标（彩色/单色两种模式），细节打磨程度相当高。

代码质量方面，项目使用了 ruff（linting）+ mypy（类型检查）+ pytest（测试），CI 流程完善，遵循 AGPL-3.0 开源协议。

Catppuccin 主题，完整支持 Mocha/Frappe/Latte/Macchiato 四款 flavor

上手门槛：零配置开箱即用

macOS 用户（推荐路径）：

brew install --cask aqua5230/usage/usage

下载安装后，右键 Open 一次通过 Gatekeeper，再点击菜单栏图标即可。无需任何配置，日志路径自动检测。

其他平台：Linux/Windows 用户可通过 uvx usage-cli 打开纯 TUI 终端界面，无需安装，但失去菜单栏集成。

CLI 深度用户：usage status --json 可将配额输出给 Starship、tmux 或任何脚本工具，完全无网络请求。

局限与争议

平台局限性：菜单栏原生应用仅支持 macOS 和 Windows，Linux 用户只能使用 TUI 版本，功能大幅缩减（无 GUI 面板、无主题、无通知）。

隐私考量：虽然日志不上传，但 usage 确实读取 Claude Code 的本地日志文件（通常在 ~/.claude/projects/）。介意者需自行评估。

依赖 Apple Silicon：macOS 版本依赖 PyObjC，虽然支持 Intel 和 Apple Silicon 双架构，但 M 系列芯片上运行更流畅。

维护活跃度：项目维护较为活跃（v0.29.x 版本），但 AGPL-3.0 协议对商业闭源项目有强制开源要求，可能不适合需要整合进闭源工具链的场景。

行业意义

usage 的出现代表了一个趋势：AI 编程工具正在从"单一使用"向"系统化管理"演进。当 token 成为真正的成本，开发者就会开始关注消耗可视化、配额预警、浪费检测这类需求。

目前市场上已有多个类似项目（如 ClaudeBar、Claude-Usage-Tracker、claude-monitor），但 usage 是其中功能最全面、主题最丰富、本地化支持最好的之一（支持简/繁体中文、英语、日语、韩语）。它不仅解决了配额焦虑，还通过 Token 节省器、AI 圆桌讨论等功能，真正帮助开发者更高效地与 AI 协作。

如果你重度使用 Claude Code、Codex 或 Antigravity，装上它，你会回来感谢我的。

可导出的 HTML 深度报告，包含趋势图与项目排名