这个项目来自 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_KEYsk-ant-...或者直接在应用的Settings面板粘贴 API Key。5. 功能测试与效果验证5.1 测试用量显示是否正确测试目的确认菜单栏能正确显示当前 Claude 用量。操作步骤启动应用。观察菜单栏是否出现应用图标。点击图标查看用量数值是否与 Anthropic 控制台一致。预期结果菜单栏出现输入账号对应的用量计数。点击图标后能看到 API Key 对应的 token 消耗数量。判断标准控制台用量为 0 或低频使用时菜单栏显示应该匹配。如果显示异常检查 API Key 是否填写正确。5.2 测试用量刷新频率测试目的验证用量数据是否能在合理时间内刷新。操作步骤用 Claude API 随便跑一次请求。等待 1 到 5 分钟。点击菜单栏图标观察用量是否增加。预期结果正常运行的应用会在定时刷新周期内更新用量。刷新频率一般是 30 秒到 5 分钟不等具体看源码。判断标准如果 10 分钟后仍未更新检查网络请求是否被拦截或代理影响。5.3 测试菜单栏显示清晰度测试目的确认菜单栏文字在小尺寸下可读。操作步骤观察菜单栏图标的文字大小。在暗色模式和亮色模式下分别检查文字对比度。预期结果即使菜单栏空间有限也能看到用量数字。不会与其他菜单栏图标重叠或遮挡。判断标准如果文字太小看不清看项目是否提供自定义显示格式的选项。5.4 测试网络异常处理测试目的验证无网络或 API 不可用时应用的稳定性。操作步骤断开网络。观察菜单栏图标是否变灰或显示占位符。重新连接网络观察是否自动恢复。预期结果应用不崩溃。显示离线或未知状态。网络恢复后自动拉取最新用量。判断标准如果应用崩溃说明错误处理不完善。如果长时间停留在旧数据状态可能需要手动刷新。6. 数据来源与接口调用原理这个工具的价值在于它能告诉你 Claude 还剩多少用量但用量数据从哪里来这是使用前必须搞清楚的问题。6.1 用量数据来源推测从 Claude 生态的常见做法来看用量读取通常有两条路径路径一读取 Claude Code 的本地元数据Claude Code 在使用过程中会把对话记录、token 消耗写入本地目录常见位置~/.claude/projects/这种方式的优点是无需额外鉴权因为 Claude Code 已经通过 OAuth 或 API Key 建立了会话缺点是只能统计 Claude Code 的消耗无法统计 Claude API 的独立调用。路径二调用 Anthropic 官方 APIAnthropic 提供用量查询接口后应用可以用 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 ClaudeUsage8.3 如果用量查询失败优先检查以下三点Anthropic API 账户是否欠费或被封禁。系统时间是否准确API 认证依赖时间戳。网络是否能正常访问api.anthropic.com。# 测试网络连通性 curl -I https://api.anthropic.com9. 最佳实践与使用建议9.1 第一次先跑最小测试拿到工具后不要直接开始大规模监控。先跑一次最小的验证启动应用。手动调用一次 Claude API。观察菜单栏数值变化。确认刷新正常后再接入日常流程。9.2 保留一套最小可运行配置把以下内容写到一个配置文件中备用{ api_key: 从环境变量读取不要硬编码, refresh_interval_seconds: 300, display_format: compact, alert_threshold: 0.8 }如果项目本身不支持配置文件可以记住以下环境变量export ANTHROPIC_API_KEY你的Key9.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 的重度用户来说这个体验提升是实打实的。建议你重点验证三件事用量数值是否准确和 Anthropic 控制台对比。刷新频率是否够用调整到适合自己的节奏。菜单栏显示是否可读不能为了追求小体积牺牲了信息可读性。最容易踩的坑是 API Key 泄露。用这个工具之前一定要确认它的网络请求只发往 Anthropic 官方域名不要顺手把自己的 Key 交给不认识的第三方服务器。如果你正好在用 Claude Code 跑自动化批量任务这个项目值得试一下。后续如果作者支持多账号切换、导出用量报表或者提供命令行版使用范围会更广。建议收藏备用。