一个原生 macOS 菜单栏应用，实时监控你的 Claude Code 用量。
Claude Max 计划有会话（5小时）和周（7天）用量限制，但没有方便的方式查看消耗了多少——你得打开 CLI 手动运行 /usage。ClaudeUsage 安静地待在菜单栏，一眼就能看到百分比，还有消耗速度预测、重置倒计时和费用追踪。
本项目受 CodexBar 启发——Peter Steinberger 开发的多 Provider AI 用量仪表盘。感谢 CodexBar 在这一领域的开创性工作。ClaudeUsage 采用不同的思路，专为 Claude Code 用户做了轻量化和安全性优化。
| ClaudeUsage | CodexBar | |
|---|---|---|
| 数据来源 | 官方 CLI /usage — Anthropic 原始数据 |
OAuth API / CLI PTY / 浏览器 cookie |
| 安全性 | 零网络请求，不碰钥匙串和凭证 | 钥匙串 + API 认证 |
| 体积 | < 1 MB，零依赖 | ~50 MB，多个框架 |
| 最低系统 | macOS 13 (Ventura) | macOS 14 (Sonoma) |
| 覆盖范围 | Claude Code（专注） | 20+ AI 服务 |
| 消耗速度预测 | ✅ | — |
| 空闲检测 | ✅ IOKit | — |
| 桌面小组件 | ✅ 毛玻璃悬浮窗 | ✅ WidgetKit |
| 费用图表 / CLI / Linux | — | ✅ |
选 ClaudeUsage — 轻量专注的 Claude 监控。选 CodexBar — 多 Provider 综合仪表盘。
- 菜单栏指示器 — 猫咪图标 🐱 旁显示当前会话用量百分比，始终可见
- 会话限制 — 5 小时滚动窗口用量，带进度条
- 周限制 — 7 天用量，带进度条（全模型 + Sonnet 单独统计）
- 重置倒计时 — 实时显示距离重置的时间，如"Resets in 2d 5h"
- 超前 / 落后 — 将你的实际消耗与线性预期速度对比
- 耗尽预估 — 如果消耗过快，显示预计何时用完（如"Runs out in 1d 3h"）
- 本地扫描
~/.claude/projects/**/*.jsonl会话日志 - 支持 Opus 4.5/4.6、Sonnet 4.5/4.6、Haiku 及旧版模型的独立定价
- 支持阶梯定价（Sonnet 超过 200K token 阈值后价格更高）
- 显示今日费用和最近 30 天费用及 token 数量
- 通过
message.id去重（流式输出会产生累积的多行记录）
- 悬浮小组件 — 毛玻璃背景的桌面小组件，跨所有桌面空间始终可见
- 双尺寸 — 小号（紧凑 180×190 方块）或中号（320×140 完整信息）
- 清新多彩 — 海洋蓝（会话）、珊瑚粉（周用量）、薄荷绿（费用）、暖紫（品牌）
- 可拖拽 — 拖到任意位置，重启后自动记住
- 零额外开销 — 与菜单栏共享同一数据源，无需额外轮询或进程间通信
- 每 15 秒通过 IOKit
HIDIdleTime检测系统空闲时间 - 达到空闲阈值后暂停所有轮询，菜单栏显示 ⏸
- 用户回来后自动恢复并立即刷新
- 可配置：1 分钟、5 分钟、10 分钟、30 分钟、1 小时、或从不
- 刷新间隔 — 1分钟, 3分钟, 5分钟, 10分钟, 30分钟
- 自动休眠 — 空闲后暂停（1分钟–1小时，或从不）
- 显示模式 — 显示剩余 % 或已用 %
- 登录时启动 — 通过 SMAppService 实现
┌─────────────────────────────────────────────────────────┐
│ ClaudeUsageApp │
│ MenuBarExtra (.window 样式) │
│ ┌──────────┐ ┌──────────────┐ │
│ │ 猫咪图标 │ │ 用量百分比 │ │
│ └──────────┘ └──────────────┘ │
├─────────────────────────────────────────────────────────┤
│ MenuBarView │
│ ┌──────────┬──────────┬──────────┬──────────────────┐ │
│ │ 会话用量 │ 周用量 │ Sonnet │ 费用统计 │ │
│ │ + 进度条 │ + 进度条 │ + 进度条 │ 今日 / 30 天 │ │
│ │ + 重置 │ + 重置 │ + 重置 │ $ + Token 数 │ │
│ │ │ + 速度 │ │ │ │
│ └──────────┴──────────┴──────────┴──────────────────┘ │
├─────────────────────────────────────────────────────────┤
│ UsageStore │
│ @MainActor, @Published 属性 │
│ ┌────────────────┐ ┌──────────────────────┐ │
│ │ refreshTimer │ │ idlePollTimer │ │
│ │ (可配置间隔) │ │ (每 15 秒) │ │
│ └───────┬────────┘ └──────────┬───────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─── Task.detached ───┐ ┌─ checkIdleState() ─┐ │
│ │ (后台线程执行) │ │ IOKit HIDIdleTime │ │
│ │ │ │ → 暂停 / 恢复 │ │
│ │ UsageFetcher.fetch │ └─────────────────────┘ │
│ │ UsageParser.parse │ │
│ │ CostScanner.scan │ │
│ └─────────────────────┘ │
└─────────────────────────────────────────────────────────┘
数据来源:
┌────────────────────────┐ ┌──────────────────────────┐
│ Claude CLI (PTY) │ │ ~/.claude/projects/ │
│ openpty → /usage 命令 │ │ **/*.jsonl │
│ → ANSI 剥离 + 解析 │ │ → token 费用扫描 │
└────────────────────────┘ └──────────────────────────┘
- 定时器触发 → 主线程调用
UsageStore.refresh() Task.detached将所有重 I/O 移到后台线程：UsageFetcher.fetch()— 通过 PTY 启动claude --allowed-tools ""，等待欢迎界面结束（600ms 安静），发送/usage，读取到停止字符串UsageParser.parse()— 剥离 ANSI 转义码（包括ESC[NC光标右移 → 替换为空格），提取百分比和重置时间CostScanner.scan()— 遍历~/.claude/projects/下最近 30 天修改的 JSONL 文件，提取每条消息的 token 用量，按 message ID 去重，应用每模型定价
- 回到主线程 — 更新 Published 属性，SwiftUI 重新渲染
ClaudeUsage/
├── Package.swift # SPM 清单 (macOS 13+, Swift 5.9)
├── build.sh # 构建 + .app 包组装脚本
├── Resources/
│ ├── Info.plist # LSUIElement=YES (不显示 Dock 图标)
│ └── AppIcon.icns # 生成的猫咪图标
├── Scripts/
│ └── make-icon.swift # CoreGraphics 图标生成器
└── Sources/ClaudeUsage/
├── ClaudeUsageApp.swift # @main 入口, MenuBarExtra, NSImage 猫咪图标
├── MenuBarView.swift # SwiftUI 弹出界面, 速度计算
├── UsageStore.swift # 状态管理, 定时器, 空闲检测
├── UsageFetcher.swift # PTY 命令行交互 (actor)
├── UsageParser.swift # ANSI 剥离, 百分比和重置时间解析
├── UsageData.swift # UsageSnapshot 数据模型
├── CostScanner.swift # JSONL 日志扫描, 每模型定价
├── DesktopWidget.swift # 桌面悬浮小组件窗口 (NSWindow + 毛玻璃)
├── WidgetViews.swift # 小号 & 中号小组件 SwiftUI 视图
└── Settings.swift # UserDefaults, SMAppService
- 从最新 Release 下载
ClaudeUsage.app.zip - 解压后将
ClaudeUsage.app拖入/Applications/ - 打开应用 — 猫咪图标出现在菜单栏
需要 macOS 13+ 和 Swift 5.9+（Xcode 15 命令行工具或独立 Swift 工具链）。
git clone https://github.com/pemagic/ClaudeUsage.git
cd ClaudeUsage
bash build.sh
cp -r ClaudeUsage.app /Applications/
open /Applications/ClaudeUsage.appbuild.sh 执行 swift build -c release，生成应用图标，组装 .app 包。无需 Xcode 工程文件。
启动后点击菜单栏的猫咪图标，弹出面板：
- Session（会话） — 5 小时滚动窗口用量（如"72% left · Resets in 3h 42m"）
- Weekly（周） — 7 天用量及消耗速度（如"Ahead (+12%) · Runs out in 2d 5h"）
- Sonnet — Sonnet 模型单独统计（如有）
- Cost（费用） — 今日和最近 30 天的估算费用及 token 数
- Refresh Now — 立即手动刷新
- Settings — 配置刷新间隔、空闲阈值、显示模式
当你停止使用电脑后，菜单栏显示 ⏸，所有轮询暂停。移动鼠标或按键后自动恢复。
- CLI 工作目录设为
/tmp/claudeusage-probe，避免 macOS TCC 对桌面/文档目录的权限弹窗 env -u CLAUDECODE防止从 Claude Code 会话内启动时出现"嵌套会话"错误- 欢迎界面可能加载 10KB+ 的 skill 数据才出现
/usage输出——获取器等待 600ms "安静期"而非固定延迟 - ANSI 光标右移码（
ESC[1C）在"current week"中出现，剥离时替换为空格 - 费用扫描使用 C 语言
fgets逐行读取，内存效率高 - Sonnet 阶梯定价：超过 200K token 后使用更高的每 token 单价
| 模型 | 输入 ($/MTok) | 输出 ($/MTok) | 缓存读取 | 缓存创建 |
|---|---|---|---|---|
| Opus 4.5/4.6 | $5 | $25 | $0.50 | $6.25 |
| Opus 4.1 | $15 | $75 | $1.50 | $18.75 |
| Sonnet 4.5/4.6 | $3 | $15 | $0.30 | $3.75 |
| Sonnet (>200K) | $6 | $22.50 | $0.60 | $7.50 |
| Haiku 4.5 | $1 | $5 | $0.10 | $1.25 |
价格对齐 Anthropic 官方公布的 API 定价（2025 年 2 月）。
- macOS 13 Ventura 或更高版本
- 已安装 Claude Code CLI 并已登录
- Claude Max 计划（用量数据仅 Max 可用）