macOS菜单栏Claude用量监控小工具：跑任务前先看一眼剩余额度

这个项目来自 Hacker News 的 Show HN，作者做了一个 macOS 菜单栏小工具，专门用来盯 Claude 的用量情况。标题写得很有意思：“small enough to read before you run it”，意思是这个工具足够轻，小到你跑 Claude 任务之前，扫一眼菜单栏就知道当前用量还剩多少。

如果你经常用 Claude Code 跑自动化任务，大概率遇到过跑着跑着突然提示opencode free usage exceeded或者Claude usage limit reached，然后整个任务中断。这个菜单栏工具解决的正是这个痛点：在任务开始之前，先看一眼用量，再决定要不要跑大批量任务。

这篇文章会带你把项目跑起来，说明它怎么读用量、怎么判断有没有剩余额度，以及实际使用中需要注意什么。

1. 核心能力速览

先看这个项目的基本情况。需要说明的是，由于项目以菜单栏工具的形式提供，实际功能相对聚焦，下面的参数以通用部署为准：

能力项	说明
项目类型	macOS 菜单栏用量监控工具
核心功能	在系统菜单栏显示 Claude usage 信息
部署平台	macOS（菜单栏原生应用）
技术栈	一般为 Swift / AppKit / SwiftUI
启动方式	编译运行或将 .app 放入应用程序目录
显存需求	不涉及，纯本机轻量工具
是否支持 CPU 推理	不涉及
是否支持 50 系显卡	不涉及
是否支持 API	该工具本身提供的是本地展示，是否附带本地 HTTP 回调需按项目源码确认
是否支持批量任务	不直接支持，但可以作为批量任务的"用量前置检查"
适合场景	Claude Code、Claude CLI 高频用户、自动化任务调度场景
主要卖点	体积小、启动快、跑任务前可快速确认用量

从材料看，这个项目解决的是典型的"用量焦虑"问题。很多 Claude Code 用户跑长任务时不会时刻盯着终端，等到发现用量超限时，任务已经中断了。菜单栏工具的核心价值是把用量信息从"需要主动查询"变成"被动可见"。

2. Claude 用量监控适用场景与使用边界

2.1 适合谁用

这个工具适合以下人群：

• Claude Code 高频使用者：每天跑代码生成、代码审查、批量重构任务的开发者。
• Claude API 调用者：自己写脚本调用 Claude API，需要控制每日预算。
• 自动化任务调度者：用 crontab 或 CI 定时触发 Claude 任务的用户。
• 多项目并行开发者：同时维护多个仓库，担心 API 配额被某个任务耗尽。

2.2 能解决什么问题

• 不用手动打开网页或终端查用量，菜单栏常驻一眼可见。
• 在跑批量任务前快速判断剩余额度，避免任务跑到一半中断。
• 配合日志工具统计每日消耗趋势，辅助预算规划。

2.3 不适合什么场景

• Windows/Linux 用户：菜单栏工具通常依赖 macOS 的 Menu Bar（菜单栏）+ NSStatusItem 机制，一般不支持跨平台。
• 移动端用量监控：如果你想在手机上查看用量，这个工具不适合。
• 多账号复杂管理：如果你的用量分散在多个 Anthropic 账号中，这个工具需要看源码是否支持多账号切换。

2.4 使用边界与合规提醒

不管你用什么方式监控 Claude 用量，都必须注意：

• API Key 是敏感信息：工具需要读取 API Key 才能查询用量。使用第三方开源工具时，先确认它不会把 Key 上传到非官方服务器。
• 订阅额度与 API 额度不同：Claude Pro/Max 订阅和 Anthropic API 是两套计费体系，菜单栏工具显示的到底是哪一套，需要先搞清楚。
• 本地网络请求：工具需要向 Anthropic 官方端点发起网络请求，存在数据泄露风险的前提是它把 Key 发给错误服务器，所以建议审查源码后再使用。
• 合法使用：用量监控本身不涉及版权问题，但如果批量任务使用了受版权保护的代码或素材，责任在使用方。

3. 环境准备与前置条件

由于该项目是 macOS 菜单栏应用，需要按原生应用的环境要求准备。以下是通用检查清单：

3.1 操作系统

• macOS 12 Monterey 或更高版本（具体取决于项目最低系统版本，需按源码确认）。
• 建议使用最新稳定版 macOS，避免菜单栏权限异常。

3.2 开发工具链

如果你需要从源码编译安装，需要准备：

# 安装 Xcode Command Line Tools xcode-select --install # 检查 Swift 版本 swift --version

如果项目使用 Swift Package Manager，还需要确保网络能正常访问 GitHub 仓库。

3.3 Claude 账户与 API Key

工具要显示用量，至少满足以下条件之一：

• Anthropic API Key（用于查询 API 用量）。
• Claude Pro/Max 订阅账号（如果项目支持登录态读取，则无需 API Key）。
• Claude Code 的本地配置（部分工具会读取~/.claude目录下的配置）。

3.4 磁盘空间与内存

• 源码编译需要约 2GB 临时空间（包含 Xcode 缓存）。
• 编译后的应用通常只有几 MB 到几十 MB。
• 运行内存占用一般不超过 100MB，因为只做菜单栏显示和定时请求。

4. 安装部署与启动方式

由于这不是一个直接提供下载链接的项目，部署方式以源码编译为主。下面给出通用流程，实际命令需要按项目 README 调整。

4.1 方式一：命令行编译启动

# 克隆项目（实际仓库地址以项目 README 为准） git clone https://github.com/yourusername/claude-usage-menu.git cd claude-usage-menu # 编译 swift build -c release # 运行 swift run

如果项目附带 Xcode 工程，也可以直接打开：

open Package.swift

然后在 Xcode 中点击 Run。

4.2 方式二：打包为 .app 使用

# 将 release 版本复制到应用程序目录 cp -R .build/release/ClaudeUsage.app /Applications/

然后从 Launchpad 或 Spotlight 启动。

4.3 首次启动的权限设置

macOS 菜单栏应用首次启动时，可能会弹出以下权限请求：

• 通知权限：用于用量超限提醒。
• 网络权限：用于访问 Anthropic API 查询用量。
• 辅助功能权限：一般不需要，除非工具要读取其他应用的界面数据。

建议全部允许，否则功能会不完整。

4.4 配置 API Key

启动后，一般需要在应用的设置界面填入 API Key。常见形式：

# 环境变量方式（如果项目支持） export ANTHROPIC_API_KEY="sk-ant-..."

或者直接在应用的Settings面板粘贴 API Key。

5. 功能测试与效果验证

5.1 测试用量显示是否正确

测试目的：确认菜单栏能正确显示当前 Claude 用量。

操作步骤：

1. 启动应用。
2. 观察菜单栏是否出现应用图标。
3. 点击图标，查看用量数值是否与 Anthropic 控制台一致。

预期结果：

• 菜单栏出现输入账号对应的用量计数。
• 点击图标后能看到 API Key 对应的 token 消耗数量。

判断标准：

• 控制台用量为 0 或低频使用时，菜单栏显示应该匹配。
• 如果显示异常，检查 API Key 是否填写正确。

5.2 测试用量刷新频率

测试目的：验证用量数据是否能在合理时间内刷新。

操作步骤：

1. 用 Claude API 随便跑一次请求。
2. 等待 1 到 5 分钟。
3. 点击菜单栏图标，观察用量是否增加。

预期结果：

• 正常运行的应用会在定时刷新周期内更新用量。
• 刷新频率一般是 30 秒到 5 分钟不等，具体看源码。

判断标准：

• 如果 10 分钟后仍未更新，检查网络请求是否被拦截或代理影响。

5.3 测试菜单栏显示清晰度

测试目的：确认菜单栏文字在小尺寸下可读。

操作步骤：

1. 观察菜单栏图标的文字大小。
2. 在暗色模式和亮色模式下分别检查文字对比度。

预期结果：

• 即使菜单栏空间有限，也能看到用量数字。
• 不会与其他菜单栏图标重叠或遮挡。

判断标准：

• 如果文字太小看不清，看项目是否提供自定义显示格式的选项。

5.4 测试网络异常处理

测试目的：验证无网络或 API 不可用时应用的稳定性。

操作步骤：

1. 断开网络。
2. 观察菜单栏图标是否变灰或显示占位符。
3. 重新连接网络，观察是否自动恢复。

预期结果：

• 应用不崩溃。
• 显示"离线"或"未知"状态。
• 网络恢复后自动拉取最新用量。

判断标准：

• 如果应用崩溃，说明错误处理不完善。
• 如果长时间停留在旧数据状态，可能需要手动刷新。

6. 数据来源与接口调用原理

这个工具的价值在于"它能告诉你 Claude 还剩多少用量"，但用量数据从哪里来？这是使用前必须搞清楚的问题。

6.1 用量数据来源推测

从 Claude 生态的常见做法来看，用量读取通常有两条路径：

路径一：读取 Claude Code 的本地元数据

Claude Code 在使用过程中会把对话记录、token 消耗写入本地目录，常见位置：

~/.claude/projects/

这种方式的优点是无需额外鉴权，因为 Claude Code 已经通过 OAuth 或 API Key 建立了会话；缺点是只能统计 Claude Code 的消耗，无法统计 Claude API 的独立调用。

路径二：调用 Anthropic 官方 API

Anthropic 提供用量查询接口后，应用可以用 API Key 主动拉取消耗数据。大致的请求结构是：

curl https://api.anthropic.com/v1/usage \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01"

实际端点、参数和返回字段需要以 Anthropic 官方文档为准。

6.2 不要被"显示数值"骗了

一个容易踩的坑是：菜单栏显示的数字不一定等于"你还能用多少"。因为：

• 订阅用户（Pro/Max）的额度刷新周期是 5 小时，API 用户是月度账单。
• Claude Code 可能有独立的限制策略，与网页版、API 版相互独立。
• 部分工具显示的可能是"本地估算值"，而不是官方精确值。

更稳妥的判断是：菜单栏工具适合做"提醒"，不适合做"精确计费依据"。最终用量请以 Anthropic 控制台为准。

7. 资源占用与性能观察

作为菜单栏小工具，资源占用是核心指标。虽然无法给出项目在具体机型的精确数字，但可以从通用角度给出观察方法。

7.1 如何观察资源占用

在 macOS 上，打开"活动监视器"按 CPU 排序：

进程名：ClaudeUsage CPU：应保持在 0% 到 5% 之间 内存：应在 30MB 到 150MB 之间

如果 CPU 持续超过 10%，说明刷新逻辑过于频繁或存在循环泄漏。

7.2 影响资源占用的因素

因素	影响
刷新频率	每秒刷新 vs 每 5 分钟刷新，功耗差异很大
动画效果	菜单栏图标如果带动画，会增加 GPU 占用
网络请求	每次请求都会创建 URLSession，频繁请求产生网络开销
日志写入	如果应用自带日志轮转，写入过于频繁会增加磁盘消耗

7.3 降低资源占用的方法

• 如果应用提供刷新间隔设置，建议设为 5 分钟以上。
• 如果菜单栏图标有动画效果，看是否支持关闭。
• 避免同时运行多个类似的用量监控工具。

8. 常见问题与排查方法

8.1 常见问题排查表

问题现象	可能原因	排查方式	解决方案
菜单栏不显示图标	应用未启动成功	检查活动监视器是否有进程	重新运行应用
显示 0 token 或空值	API Key 无效	在 Anthropic 控制台验证 Key	重新生成 Key
用量数据不刷新	网络被代理拦截	查看控制台日志	为应用配置系统代理绕过规则
应用崩溃	系统版本过低或缺少权限	查看崩溃日志	升级 macOS 或重新签名
CPU 占用过高	刷新频率设置过短	查看设置面板	延长刷新间隔
启动提示"无法打开，因为 Apple 无法检查其是否包含恶意软件"	Gatekeeper 拦截	右键打开应用	使用xattr -dr com.apple.quarantine /Applications/ClaudeUsage.app清除隔离属性
无法读取 Claude Code 数据	权限不足或目录变化	检查~/.claude目录是否存在	确认 Claude Code 早已完成登录

8.2 显式检查命令

# 检查 Claude Code 本地项目记录 ls -la ~/.claude/projects/ # 检查环境变量是否设置 echo $ANTHROPIC_API_KEY # 检查应用进程是否运行 ps aux | grep ClaudeUsage

8.3 如果用量查询失败

优先检查以下三点：

1. Anthropic API 账户是否欠费或被封禁。
2. 系统时间是否准确（API 认证依赖时间戳）。
3. 网络是否能正常访问api.anthropic.com。

# 测试网络连通性 curl -I https://api.anthropic.com

9. 最佳实践与使用建议

9.1 第一次先跑最小测试

拿到工具后，不要直接开始大规模监控。先跑一次最小的验证：

1. 启动应用。
2. 手动调用一次 Claude API。
3. 观察菜单栏数值变化。
4. 确认刷新正常后，再接入日常流程。

9.2 保留一套最小可运行配置

把以下内容写到一个配置文件中，备用：

{ "api_key": "从环境变量读取，不要硬编码", "refresh_interval_seconds": 300, "display_format": "compact", "alert_threshold": 0.8 }

如果项目本身不支持配置文件，可以记住以下环境变量：

export ANTHROPIC_API_KEY="你的Key"

9.3 批量任务前的用量前置检查

这是这个工具最有价值的场景。假设你准备跑一批代码重构任务，可以在脚本开头加入一个简单的用量检查：

#!/bin/bash # 启动菜单栏工具后，人工确认用量充足 echo "请确认菜单栏 Claude 用量充足" echo "剩余用量低于 20% 时，建议暂停批量任务" # 然后才开始批量任务 for repo in $(cat repos.txt); do claude -p "refactor this project" --directory "$repo" done

用这种方式跑任务，能显著降低"任务跑到一半被用量限制中断"的概率。

9.4 隐私与安全注意事项

既然这个工具要读取你的 Claude 用量信息，就可能涉及以下隐私问题：

• API Key 存储位置：确认 Key 是否明文存在本地偏好设置中。
• 是否上传数据：检查源码是否有除 Anthropic 官方端点之外的网络请求。
• 日志内容：如果工具会记录用量变化，确认日志目录权限为当前用户私有。

建议在干净环境中测试工具，仔细审查代码后再输入真实的 API Key。

9.5 与其他工具的配合

菜单栏用量监控适合作为"被动提醒"，但如果要精细控制用量，还需要配合：

• Claude Code 的自动暂停配置：在脚本中判断退出码，如果是用量超限错误，则自动暂停并等待。
• 预算告警 API：如果用量数据可以通过接口获取，可以用海外服务器定时抓取并邮件告警。
• 本地记录：将每天用量写入 CSV，周复盘时可以看趋势。

10. 总结与下一步

这个项目的核心价值不是在技术上多复杂，而是把"跑任务前查看用量"这个动作从 30 秒缩短到了 2 秒。对于 Claude Code、Claude CLI 的重度用户来说，这个体验提升是实打实的。

建议你重点验证三件事：

1. 用量数值是否准确：和 Anthropic 控制台对比。
2. 刷新频率是否够用：调整到适合自己的节奏。
3. 菜单栏显示是否可读：不能为了追求小体积牺牲了信息可读性。

最容易踩的坑是 API Key 泄露。用这个工具之前，一定要确认它的网络请求只发往 Anthropic 官方域名，不要顺手把自己的 Key 交给不认识的第三方服务器。

如果你正好在用 Claude Code 跑自动化批量任务，这个项目值得试一下。后续如果作者支持多账号切换、导出用量报表，或者提供命令行版，使用范围会更广。建议收藏备用。