# usage ### 在 macOS 菜单栏和 Windows 系统托盘中查看 Claude Code、Codex、Antigravity 和 Grok CLI 配额。 在会话中途耗尽配额的代价很高，尤其是在依赖 Claude Code 的长时间重构或调试期间。`usage` 会在你触及限额前显示 5 小时和每周限额，并始终保持可见。无需运行命令，也无需打开页面；答案就在你平时已经会看的位置。 [繁體中文](README.zh-TW.md) · 简体中文 · [English](../README.md) · [日本語](README.ja.md) · [한국어](README.ko.md)  |  [Discussions](https://github.com/aqua5230/usage/discussions)  |  [官方介绍页](https://aqua5230.github.io/usage/) [](https://github.com/aqua5230/usage/stargazers) [](https://github.com/aqua5230/usage/actions/workflows/check.yml) [](https://github.com/aqua5230/usage/releases/latest) [](https://pypi.org/project/usage-cli/) [](https://www.python.org/) [](https://github.com/aqua5230/usage/releases/latest) [](../LICENSE) [](https://www.bestpractices.dev/projects/13538)

Claude Code 和 Codex 的数值以被动方式从你电脑上已有的日志文件读取，因此**查看配额永远不会调用 Anthropic 或 OpenAI 的 LLM API**，也永远不会消耗你的 token。Antigravity 是唯一的例外：它的配额来自 Google 官方配额接口，使用的是 Antigravity CLI 本就保存在本机的登录身份——这只是一次元数据查询，同样不会消耗你的模型配额。 ## 快速开始 ```bash brew install --cask aqua5230/usage/usage ``` **不是 macOS？** `uvx usage-cli` 在任何系统都能打开终端界面，Linux 也行——无需安装，也没有菜单栏。 它会自动安装到 Applications 文件夹。先打开一次；macOS 15 及更高版本若被拦截，到“系统设置”→“隐私与安全性”，向下滚动，点击**“仍要打开”**。macOS 14 及更早版本：右键点击 **“打开”** 以通过 Gatekeeper。放行后点击菜单栏图标。想直接下载或查看完整设置流程？请参见下方的[安装](#安装)。 **快速跳转：** [功能一览](#功能一览) · [隐私与数据来源](#隐私与数据来源) · [系统要求](#系统要求) · [安装](#安装) · [设置状态栏](#首次启动设置状态栏) · [Windows 支持](#windows-支持) · [主题图库](#主题图库) · [故障排除](#故障排除) · [对比](#对比) · [不适合谁](#不适合谁) · [开发](#开发) ## 功能一览 ### 实时可见 - **常驻监视器：** 配额常驻菜单栏，以绿色到红色的颜色编码显示。需要完整的会话、每周和各项目明细时，点击即可查看。 - **Antigravity 支持：** Antigravity（Gemini）的会话与每周配额以第三张卡片出现在除了 World Cup 2026 以外的每一款面板（该款维持两队对战 HUD）。数值直接向官方配额 API 查询，使用的是 Antigravity CLI 本就保存在你机器上的登录身份——每隔几分钟自动刷新，重置倒计时实时递减。 - **Grok CLI 支持：** 第四张卡片直接读取 Grok CLI 自己写在本地的调试日志算出每周配额百分比，不做任何网络调用。Grok CLI 没有提供会话或燃烧率数据，所以这张卡片只显示一条每周进度条；但它的逐次 token 用量一样会算进今日花费与各项目总计，跟 Claude Code、Codex 一样。 - **服务状态警示：** Claude Code、Claude API 或 Codex API 发生故障或性能降级时，相关面板底部会显示橘红警示横幅，数值仅读取官方公开的 Statuspage.io 状态页——绝不调用 LLM 使用量 API。Antigravity 因没有可用的公开状态页，暂不支持。 - **上下文提醒与通知：** 当上下文窗口达到 70%（填得快时会提前）时，状态栏会提示你使用 `/clear` 或 `/compact`，避免浪费 token。你也可以选择接收关于配额限额和恢复的系统通知。 - **缓存健康度：** 状态栏会显示 Claude Code 的 prompt cache 命中率与过期倒计时，让你一眼判断现在收尾还能沿用已缓存的内容，还是快要冷掉、得整份重新发送。需要 Claude Code 2.1.251 以上；旧版不会出现这一段。 - **隐藏区块：** 没全都用？点击一次即可从菜单栏和面板中完全隐藏 Claude Code、Codex、Grok CLI 或 Antigravity 区块。 ### 工作流辅助 - **进度管家：** 打开新的 Claude Code 会话时，`usage` 会直接把你上次的进度交给 AI，包括上次请求、未提交的变更和未完成的待办事项。无需 `/resume`，无需回顾。完全本地运行，默认关闭。 - **Token 节省器：** 菜单栏开关会要求 Claude Code 和 Codex 在当前会话中更简洁、更白话地回答，在保持代码和错误信息逐字节不变的同时节省输出 token。轻量的逐消息提醒能避免长对话中的回复逐渐变得冗长——在真实会话的 A/B 测试中，对话后期回复维持缩短约 40%，而不是漂移变长 84%。 - **终端集成：** `usage status --json` 会将你的 Claude Code 和 Codex 额度交给任何可以运行命令的工具——Starship、tmux 或你自己的脚本。与菜单栏读取相同的本地文件，无网络请求。[现成的片段](DEVELOPMENT.md#quota-status-for-other-tools-usage-status)。 - **Token 浪费健康检查：** 每日后台诊断会扫描日志中的浪费问题，包括重复读取文件、污染目录和冗长的 Bash 输出。发现问题时会显示一行提示；对 AI 说“show me”，它会引导你完成修复。 ### AI 协作 - **AI 更新日报：** 打开每天自动更新的公开[网页](https://aqua5230.github.io/ai-updates/)，涵盖 Claude Code、Codex、Antigravity 三套工具，保留完整历史。已审核的更新显示五语白话版，未审核的显示官方原文。 ### 报告与洞察 - **深入 HTML 报告：** 可分享的 HTML 深度报告，展示每日和每周 token 趋势、项目排名和费用——包含带有贡献热图和“Wrapped”摘要的年度回顾。“最近在做什么”一区列出 Claude Code 为你近期对话取的名字，让数字有脉络可对。可导出为 .html、.csv 或 .png，完全离线，并可选择遮蔽项目名称，这些标题也会一并遮蔽。 ### 体验与自定义 - **14 个视觉主题：** 可切换面板风格，包括默认（Default）、Matrix、Windows 95、复古报纸（Newspaper）、Cloud Observation、Midnight Aquarium、Prism Arcade、Black Hole、World Cup 2026、蝶类图鉴（Lepidoptera）、候鸟迁徙（Migration）、彩绘玻璃、折纸和 Catppuccin（官方配色，四款 flavor 全支持）。 - **面板自由摆放：** 面板不再固定在菜单栏图标下方。在任何空白处按住即可拖动到你想要的位置，下次打开仍保留在原位。切换到其他 App 时也不会消失，再次点击菜单栏图标或按 Esc 键才会关闭。 - **拖拽排序：** 按住任意配额卡上下拖拽即可交换顺序——这一排列在所有包含配额卡的主题间共享（除 World Cup 2026 之外），并在重启后保留。 - **自动本地化：** 界面文本提供繁体中文、简体中文、英语、日语和韩语，并自动匹配系统设置。 ## 隐私与数据来源 - Claude Code 和 Codex 的数值**仅从本机本地日志文件**读取；读取这些数值**不会调用 Anthropic 或 OpenAI 的 LLM API**。 - Antigravity 配额需要联网，且只有你实际使用它才会发生：配额通过 Antigravity CLI 登录后保存的 OAuth 凭据，向 Google 官方配额接口查询——依 CLI 版本不同，该凭据读自 macOS 钥匙串、Windows 凭据管理器，或本地 token 文件。`usage` 只读取该凭据而不写回，任何刷新后的 access token 也只保留在内存中；该调用本身只读取配额信息，绝不消耗你的模型配额。 - 后台网络活动范围：上述 Antigravity 配额／token 接口、用于标记故障的 Claude 与 Codex 公开状态页、用于估算费用的公开模型价格表（离线时回退到内置价格），以及偶尔在 GitHub 检查新版本。Claude Code 与 Codex 的日志内容不会被上传。 ## 系统要求 - macOS 12（Monterey）或更新版本，或 Windows 10/11 - 至少使用过一次 Claude Code、Codex 或 Antigravity（以便存在本地使用数据）。 - （仅限源代码运行）Python 3.13。 ## 安装 ### 1. Homebrew（推荐） 通过 Homebrew 安装后，只需一次 `brew upgrade --cask usage` 即可保持最新。 ```bash brew install --cask aqua5230/usage/usage ``` *（首次启动：macOS 15 及更高版本，打开“系统设置”→“隐私与安全性”，向下滚动，点击**“仍要打开”**。macOS 14 及更早版本，在 Finder 中右键 `usage.app` → **“打开”** 以通过 Gatekeeper）。* ### 2. 下载 macOS App 1. 从 [GitHub Releases 页面](https://github.com/aqua5230/usage/releases/latest)下载最新的 `usage.app.zip`。 2. 解压后，将 `usage.app` 拖入 Applications 文件夹。 3. 首次启动：macOS 15 及更高版本，打开“系统设置”→“隐私与安全性”，向下滚动，点击**“仍要打开”**。macOS 14 及更早版本，在 Finder 中右键 `usage.app` → **Open** → 确认 Open。 ### 3. uvx（零安装，跨平台） 执行 `uvx usage-cli` 即可直接打开终端界面。uv 会自动准备 Python 3.13，无需另行安装 Python。 若要持续安装命令，执行 `uv tool install usage-cli`，之后使用 `usage`（例如 `usage status --json`）。这种安装方式只有 CLI（命令行界面），不含菜单栏 App。 Linux 上运行 `usage setup` 也能装好 Claude Code 的状态栏，配额会像 macOS 与 Windows 一样显示在提示符下方，CI 会在 Ubuntu 上验证这条路径。菜单栏与系统托盘 App 仍然只有 macOS 与 Windows 才有。 ## 首次启动：设置状态栏 如果你用过 Codex，`usage` 会自动读取其历史记录。对于 Claude Code，请在应用弹出面板中点击 **“Set Up Status Line”** 按钮以安装同步 hook。 之后重启相应工具（macOS 请将 Claude Code 用 Cmd+Q 完全退出后重新打开；Windows 请重启终端或重新开启会话）。 同一颗按钮在你装了 Antigravity CLI 与 Grok CLI 时，也会一并帮它们设置状态栏；没装的话什么都不会写入。你自己在那边设置过的状态栏会先备份起来，关掉开关时还原。 设置完成后，Claude Code 窗口底部会显示如下状态栏：

## Windows 支持 Windows 原生支持完整核心功能：系统托盘 UI、Claude Code 状态栏 hook 和 Codex 记录解析均可使用。从[最新 GitHub Release](https://github.com/aqua5230/usage/releases/latest)下载 `usage-windows.zip`，解压后直接运行 `usage.exe`，无需安装。系统托盘 UI 需要 Microsoft Edge WebView2 Runtime；Windows 10 和 11 通常已经内置。 系统托盘图标会随 Claude 配额百分比更新；提示文字会汇总 Claude 和 Codex 的各个窗口。左键通过 WebView2 打开与 macOS 相同的 14 款主题面板（默认加另外十三款）；右键只有「重设面板位置」和「结束」；面板切换、刷新、开机自启和检查更新都在面板菜单中。 Windows 的差异：面板显示在工作区右下角，而不是紧贴系统托盘图标；更新提示使用系统 Yes/No 对话框。 ### 代码签名政策 Free code signing provided by [SignPath.io](https://about.signpath.io/), certificate by [SignPath Foundation](https://signpath.org/). 团队角色： - 提交者与审查者：[aqua5230](https://github.com/aqua5230) - 批准者：[aqua5230](https://github.com/aqua5230) 隐私政策：除非用户或安装、操作此程序的人员明确要求，否则本程序不会将任何信息传输至其他网络系统。有关 `usage` 代你发出的网络调用及如何避免，请参阅[隐私与数据来源](#隐私与数据来源)。 ## 主题图库 直接在界面中切换 **14 个视觉主题**：

## 故障排除 如果菜单栏显示 `--`，通常并非故障，只是尚无本地数据。 | 症状 | 可能原因 | 解决方法 | |---------|--------------|-----| | 菜单栏显示 `--` | 尚无数据，或 Claude Code hook 未刷新 | 进行一次 Codex 对话。对于 Claude Code，点击“设置状态栏”（源码安装则运行 `python3 main.py --setup`） | | 运行 `usage.app` 里的 `main.py` 报 `ImportError` | 打包版的 `main.py` 需要 app 自带的解释器，无法手动运行 | 别运行那一份。改点 app 里的“设置状态栏”，或 clone 源码从源码运行 | | 误点“Quit” | 进程已终止 | 从 Spotlight 或 Applications 重新启动 `usage.app`。（`launchctl start com.lollapalooza.usage` 仅在你开启过“开机自启”时有效。） | | 状态显示“N minutes stale” | Claude Code 未运行 | 打开 Claude Code 并让它运行 | | Codex 区块为空 | 未找到 Codex 历史记录 | 进行一次 Codex 对话以生成日志 | | 今日费用显示 $0.00 | 缺少模型价格 | 删除 `~/.usage/pricing_cache.json`，或检查 `USAGE_DEBUG=1` | | Antigravity 卡片未显示 | 未安装或未登录 Antigravity CLI | 安装并登录 Antigravity CLI；后台配额查询成功后卡片会自动出现 | | App 无法打开 | macOS Gatekeeper 阻止了它 | macOS 15 及更高版本：系统设置 → 隐私与安全性 → 向下滚动 → 仍要打开。macOS 14 及更早版本：在 Finder 中右键 `usage.app` → 打开 | ## 对比 | 功能 | usage | ccusage | TokenTracker | |---------|:-----:|:-------:|:------------:| | 始终显示在屏幕上 | ✅ | — | ✅ | | macOS 菜单栏与 Windows 系统托盘 | ✅ | — | 仅限 macOS | | Claude Code 与 Codex 用量 | ✅ | 仅 Claude | ✅ | | Antigravity（Gemini）用量 | ✅ | — | — | | Grok CLI 用量 | ✅ | — | — | | Claude Code 与 Codex 服务状态警示 | ✅ | — | — | | HTML 深度报告与界面 | ✅ | ✅ | — | | AI 更新日报 | ✅ | — | — | | 进度管家与 Token 节省器 | ✅ | — | — | | Token 浪费健康检查 | ✅ | — | — | | 读取配额时不调用 LLM API | ✅ | ✅ | ✅ | | 开源许可证 | AGPL-3.0 | MIT | — | ## 不适合谁 - 你完全生活在终端中，不想要任何后台运行的菜单栏图标——单次执行的 CLI 工具会更适合你。 - 你没有在使用 Claude Code、Codex 或 Antigravity——因为这样 `usage` 就没有可以读取的本地使用数据。 - 你使用的是 Linux——目前仅支持 macOS 和 Windows。 ## 开发 从源码构建、配置自定义 Agent 或运行终端 TUI？请参阅**[开发文档](DEVELOPMENT.md)**。 ## 许可证 采用 AGPL-3.0-only 许可证（见 [LICENSE](../LICENSE)）。如你 fork 或重新分发修改后的版本，请注明原作者并链接回： https://github.com/aqua5230/usage