richhickson/claudecodeusage

macOS menu bar app showing Claude Code usage limits (session/weekly/per-model/overage) with alerts and click-to-focus when a Claude Code session needs your attention

Claude Usage – macOS menubar helper for Anthropic Claude Code

What it is – 一个轻量级的原生 Swift macOS 应用，驻留在菜单栏中，实时向您展示您已消耗了多少 Claude Code 额度。它还会在 Claude Code 会话等待您的输入时通知您，让您可以直接跳转到运行该会话的终端标签页。

Why it matters – Claude Code（Anthropic Claude 模型的 CLI）执行按会话、每周和每月的使用限制。密切关注这些限制有助于您避免意外的超额费用，并防止会话无声地停滞。

Core features

Feature	What you get
Usage tracking	显示当前会话使用情况、每周限制（包括 Fable/Opus 等特定模型的限制）以及每月超额支出。颜色（绿色 < 70 %, 黄色 ≥ 70 %, 红色 ≥ 90 %）提供即时状态检查。
Auto-refresh	每 5 分钟查询一次 Anthropic 的使用情况 endpoint，在网络或 keychain 出现问题时重试，并在从睡眠中唤醒时刷新。
Session alerts (opt-in)	当 Claude Code 会话需要您的权限或输入时，会出现一个带有计数器的铃铛图标。可以切换 macOS 通知，并且点击通知或列表项可以跳转到对应的 Terminal/iTerm2 标签页。
Live session list	在弹出窗口中，您可以看到每个受控会话的状态：needs you 🔔, working ⚙️, 或 finished ✅。
Claude Code settings editor	您可以通过应用来编辑全局 `CLAUDE.md` 文件，并调整控制本地转录本保留时长的 `cleanupPeriodDays`。
Convenience	登录时启动开关、内置的更新检查器，以及轻量级的占用（原生 Swift，无额外运行时）。

How it works under the hood

Credentials – 应用会从 macOS Keychain 中读取您的 Claude Code OAuth token（密码永远不会离开机器）。
Usage data – 它调用未公开的 Anthropic endpoint api.anthropic.com/api/oauth/usage 来获取配额信息。
Session monitoring – 当您启用通知时，应用会在 ~/.claude/settings.json 中写入一个微小的 POSIX-sh hook，Claude Code 在每个会话中运行此 hook，并将 JSON 状态文件写入 ~/.claude/claudeusage/。菜单栏应用会监视该目录并相应地更新 UI/通知。
Click-to-focus – macOS 辅助功能权限允许应用向 Terminal/iTerm2 告知要选择与会话 ID 匹配的标签页，从而让您可以立即响应。

Installation & getting started

Download – 从 Releases 页面获取最新的 ClaudeUsage.zip，解压并将其中的 ClaudeUsage.app 拖入 Applications 文件夹。
First launch – 第一次使用时，右键点击 → Open（macOS 会针对未签名应用发出警告）。应用会自动定位您的 Claude Code 凭据。
Optional – build from source – Clone 仓库，在 Xcode 中打开 ClaudeUsage.xcodeproj，然后使用 ⌘B 编译并使用 ⌘R 运行。
Enable alerts – 点击菜单栏弹出窗口中的齿轮图标，切换 Alert when a session needs attention。应用会为您在 ~/.claude/settings.json 中安装/移除 hook。

Requirements

macOS 13 (Ventura) or newer
Claude Code CLI 已安装 (npm i -g @anthropic-ai/claude-code) 且已登录 (claude)

Privacy & licensing

无遥测数据；唯一的网络调用是向 Anthropic 的官方使用情况 API。
MIT 许可的源码 – 您可以自由地进行审计或修改。
非官方工具 – 与 Anthropic 无关；它依赖于一个可能发生变化的未公开 API。

Made by @richhickson