Claude 使用跟踪器

---

概述

Claude 使用跟踪器是一款轻量级的原生 macOS 菜单栏应用，可实时监控您的 Claude AI 使用限制。它完全由 Swift 和 SwiftUI 构建，提供简洁直观的界面，用于跟踪您的 5 小时会话窗口、每周使用限制以及 Opus 特定的用量。

主要功能

• 多账户支持：管理无限数量的 Claude 账户，每个账户拥有独立的凭据和设置
• 多账户显示：在菜单栏中同时监控所有账户
• Claude Code 集成：同步 CLI 账户，并在切换账户时自动切换凭据
• 实时监控：按账户跟踪会话、每周、API 控制台的使用情况及 API 费用
• 使用历史：交互式图表，记录随时间变化的会话、每周和账单数据
• 全局快捷键：系统范围内的键盘快捷键（无需辅助功能权限）
• 无头模式：可通过远程桌面在无头 Mac 上运行
• 可自定义界面：5 种图标样式 + 3 种颜色模式（多色/灰度/单色）+ 余量/已用量百分比切换
• 智能自动化：自动启动会话、自动切换账户、阈值通知
• 开发者工具：终端状态行集成，显示模型、上下文、账户信息、进度标记和颜色模式
• 隐私优先：本地存储，无遥测，无云同步
• 原生性能：轻量级 Swift/SwiftUI 设计，专为 macOS 打造

---

新增内容

• v3.0.3 (2026-03-10)：新增 6 级进度系统（舒适 → 危急），并在进度条上显示彩色进度标记；提供 3 种颜色模式（多色/灰度/单色）供菜单栏和状态行使用；新增标签切换（Ctx/Usage/Reset）；采用 24 小时制；调整预览颜色以匹配终端；修复了菜单栏渲染中的 CPU 自旋循环问题。

• v3.0.2 (2026-03-10)：新增 API 费用跟踪功能，并附每日图表；支持基于浏览器的身份验证（WKWebView 登录）；利用速率限制头部信息进行 CLI OAuth 认证；优化弹出窗口的自适应大小；新增三方式时间显示选择器；调整绿色配色方案使其更柔和；增加会话密钥到期提醒功能。

• v3.0.1 (2026-03-08)：弹出窗口中新增设置选项卡（剩余时间切换）；修复了多显示器下的 CPU 显示问题。

• v3.0.0 - 重大更新 (2026-03-08)：

  • 无头模式：支持通过远程桌面在无头 Mac 环境中运行
  • 使用历史：交互式时间线图表，并可导出为 JSON/CSV 格式
  • 全局键盘快捷键：可配置热键（无需辅助功能权限）
  • 自动切换账户：当会话限额达到时自动切换账户
  • 无边框设置窗口：采用全息设计，配备自定义交通灯提示
  • 新增 6 个状态行组件：包括模型名称、上下文窗口、账户名称等
  • 时间进度标记与进度感知着色：智能进度指示器
  • 网络调试视图：定时捕获请求/响应详情并进行查看
  • 简体中文支持（第 9 种语言）
  • 移植了来自 novastate 分支的 12 项改进，包括 CLI 自动检测、从睡眠唤醒后刷新以及自定义通知阈值等功能。

• v2.3.0 – 多账户菜单栏显示，新增剩余百分比切换功能

• v2.2.0 – 支持多账户管理、CLI 集成以及韩语本地化

• v2.1.0 – 引入 3 步设置向导，确保智能组织功能的保留

• v2.0.0 – 实现 Apple 代码签名、自动更新及 Keychain 安全保护

查看完整发布历史

---

开始使用

先决条件

在安装 Claude 使用跟踪器之前，请确保您具备以下条件：

• macOS 14.0 (Sonoma) 或更高版本：请通过苹果菜单 → 关于本机进行检查
• 有效的 Claude AI 账户：请前往 claude.ai 注册

身份验证（任选其一）：

• 最简单：已安装并登录 Claude Code，应用程序将自动使用 CLI 凭据（v2.2.2 及以上版本）
• 浏览器登录：通过内置浏览器登录——会话密钥将自动提取（v3.0.2 及以上版本）
• 手动方式：通过网页浏览器访问 claude.ai 提取会话密钥（Chrome、Safari、Firefox 等）

注意：若要集成终端状态行，即使使用 Claude Code OAuth，仍需手动配置会话密钥。

安装

选项 1：Homebrew（推荐）

brew install --cask hamed-elfayome/claude-usage/claude-usage-tracker

或者先 tap 再安装：

brew tap hamed-elfayome/claude-usage
brew install --cask claude-usage-tracker

注意：从 v2.0.0 开始，该应用已正式使用 Apple 开发者证书签名。无需任何安全绕过操作！

更新方法：

brew upgrade --cask claude-usage-tracker

或者使用内置的自动更新功能（设置 → 更新）。

卸载方法：

brew uninstall --cask claude-usage-tracker

选项 2：直接下载

下载 Claude-Usage.zip

1. 从上述链接下载 .zip 文件。
2. 解压文件（双击或使用归档实用程序）。
3. 将 Claude Usage.app 拖到您的应用程序文件夹中。
4. 双击启动——大功告成！

v2.0.0+ 注意：该应用现已正式使用 Apple 开发者证书签名。您可以像安装和运行其他 Mac 应用程序一样进行安装和运行，无需任何安全警告或绕过操作。

自动更新：一旦安装完毕，应用会自动检查更新，并在有新版本时通知您（设置 → 更新）。

选项 3：从源代码构建

# 克隆仓库
git clone https://github.com/hamed-elfayome/Claude-Usage-Tracker.git
cd Claude-Usage-Tracker

# 在 Xcode 中打开
open "Claude Usage.xcodeproj"

# 构建并运行（⌘R）

快速入门指南

选项 A：使用 Claude Code 自动设置（最简单）

v2.2.2 新增功能：如果您已安装并登录了 Claude Code，应用将自动运行！

1. 安装 Claude Code（如果尚未安装）

   • 从 claude.com/claude-code 下载。
   • 使用 claude login 登录。

2. 启动 Claude Usage Tracker

   • 应用会自动检测您的 Claude Code 账户。
   • 无需手动配置！

3. 验证是否正常工作

   • 点击菜单栏图标。
   • 您应立即看到使用统计信息。

选项 B：浏览器登录（v3.0.2+）

如果您不使用 Claude Code，可以直接通过应用登录：

1. 点击菜单栏图标，选择“设置”。
2. 进入“个人使用” 选项卡。
3. 点击“登录 Claude.ai” — 会打开一个嵌入式浏览器。
4. 使用 Claude.ai 凭据登录（邮箱、Google SSO 等）。
5. 会话密钥会自动提取 — 应用会验证并保存它。
6. 从列表中选择您的组织 并确认。

选项 C：使用会话密钥手动设置

如果您更倾向于手动配置：

步骤 1：提取您的会话密钥

1. 打开 Claude AI

   • 在浏览器中访问 claude.ai。
   • 确保您已登录。

2. 打开开发者工具

   • Chrome/Edge：按 F12 或 Cmd+Option+I（macOS）/ Ctrl+Shift+I（Windows）。
   • Safari：在偏好设置 → 高级中启用开发者菜单，然后按 Cmd+Option+I。
   • Firefox：按 F12 或 Cmd+Option+I（macOS）/ Ctrl+Shift+I（Windows）。

3. 导航到 Cookie

   • 转到：Chrome/Edge 的 Application 选项卡 或 Firefox 的 Storage 选项卡。
   • 展开：Cookies → https://claude.ai。
   • 找到：sessionKey cookie。
   • 复制：其值（以 sk-ant-sid01-... 开头）。

步骤 2：配置会话密钥

1. 点击菜单栏图标，选择“设置”。
2. 进入“个人使用” 选项卡。
3. 展开“高级：手动会话密钥”。
4. 粘贴您的会话密钥，然后点击“测试连接”。
5. 从列表中选择您的组织。
6. 检查并点击‘保存配置’。

步骤 3：验证是否正常工作

1. 检查菜单栏：您应该能在菜单栏中看到 Claude Usage 图标。
2. 点击图标：会弹出一个显示使用统计信息的窗口。
3. 查看数据：会话使用量、每周使用量以及重置计时器都应正确显示。

成功！ 应用现在正在监控您的 Claude 使用情况。

后续步骤

• 自定义图标：前往设置 → 外观，选择您喜欢的菜单栏样式。
• 启用通知：设置 → 通知，以接收阈值提醒。
• 自动开始会话：设置 → 会话管理，以启用自动会话初始化。
• 终端集成：设置 → Claude Code，以设置状态行（需要会话密钥配置）。
• 键盘快捷键：设置 → 快捷键，以配置全局热键。

---

高级配置

手动会话密钥设置

如果您希望手动配置会话密钥，而不是使用设置向导：

# 创建会话密钥文件
echo "sk-ant-sid01-您的会话密钥在这里" > ~/.claude-session-key

# 设置安全权限（对安全性很重要）
chmod 600 ~/.claude-session-key

创建文件后，启动应用，它将自动检测会话密钥。

---

多账号管理

v2.2.0 新增功能：Claude Usage Tracker 现在支持无限个账号，允许您无缝管理多个 Claude 账户，并实现凭据的自动切换。

v3.0.0 新增功能：当会话限额达到时自动切换账号、使用历史跟踪以及全局键盘快捷键！

功能

个人资料管理

• 无限个人资料：为不同的 Claude 账户创建任意数量的个人资料
• 多个人资料显示：在菜单栏中同时显示所有个人资料
  • 在单个模式（仅显示当前活动个人资料）和多个人资料模式之间切换
  • 每个个人资料都以独特的图标样式和设置显示
  • 点击任意个人资料图标即可查看其使用详情
  • 每个个人资料可独立设置刷新频率
• 趣味自动命名：个人资料会自动生成类似“量子羊驼”、“狡猾企鹅”、“涡轮树懒”等名称
• 自定义名称：将个人资料重命名为你喜欢的任何名称
• 快速切换：通过弹出式下拉菜单或设置侧边栏即时切换个人资料
• 个人资料徽章：视觉指示器显示哪些个人资料拥有 Claude.ai 凭证和 CLI 账户

Claude Code CLI 集成

• 一键同步：将当前登录的 Claude Code 账户同步到某个个人资料
• 自动切换：切换个人资料时，CLI 凭证会自动更新
• 凭证显示：查看遮蔽后的访问令牌和订阅类型
• 智能重新同步：在切换个人资料之前，凭据会自动刷新，以捕捉 CLI 的变化
• 每个个人资料独立的 CLI：每个个人资料可以有自己的 Claude Code 账户，也可以共享系统账户

每个个人资料的设置

每个个人资料都有独立的设置：

• 凭证：独立的 Claude.ai 会话密钥、API 密钥和组织 ID
• 外观：独立的图标样式和单色模式
• 刷新间隔：自定义刷新频率（5-300 秒）
• 自动开始会话：可按个人资料启用或禁用
• 通知：独立的阈值提醒（75%、90%、95%）
• 使用数据：按个人资料分别记录

个人资料切换器

可在多个位置访问个人资料切换器：

• 弹出式标题栏：带有个人资料徽章的下拉菜单
• 设置侧边栏：带有视觉指示器的当前活动个人资料选择器
• 管理个人资料选项卡：完整的个人资料管理界面

使用方法

1. 创建个人资料：

   • 前往设置 → 管理个人资料
   • 点击“创建新个人资料”
   • 自动生成一个有趣的名称，或者输入你自己的名称

2. 配置凭证：

   • 在侧边栏中切换到所需的个人资料
   • 前往 Claude.AI / API 控制台 / CLI 账户选项卡
   • 输入凭证（每个个人资料独立）

3. 同步 Claude Code（可选）：

   • 在终端中登录 Claude Code
   • 打开设置 → CLI 账户
   • 点击“从 Claude Code 同步”
   • 现在当你切换个人资料时，CLI 凭证会自动更新！

4. 切换个人资料：

   • 点击弹出式下拉菜单
   • 或使用设置侧边栏的选择器
   • CLI 凭证会自动应用

---

特性

安装与更新

• 官方 Apple 代码签名：专业签名的应用程序，安装方式与任何 Mac 应用程序相同
• 自动更新：内置 Sparkle 框架驱动的更新系统
• 一键安装：无需安全绕过或手动批准
• 更新通知：在有新版本可用时收到通知

使用情况跟踪与监控

• 实时监控 5 小时会话、每周限额以及 Opus 特定的使用情况
• API 控制台使用情况跟踪，配备月度费用仪表盘和每日费用图表
• 按 API 密钥细分的费用明细，详细到模型级别
• 为 Claude Extra 订阅者提供额外使用费用跟踪
• 根据消耗水平采用自适应的绿色/橙色/红色颜色编码指示器
• 智能倒计时定时器，用于会话和每周重置，提供三种显示方式（时间、剩余时间或两者兼备）

菜单栏与界面

• 5 种可定制的图标样式：电池型、进度条型、仅百分比型、带进度条的图标型、紧凑型
• 多指标图标：可同时显示会话、每周和 API 使用情况的独立图标
• 3 种颜色模式：多色（基于阈值）、灰度（根据外观模式调整）、单色（自定义十六进制）
• 6 级节奏系统：根据预计使用情况对节奏标记进行着色（绿色/蓝绿色/黄色/橙色/红色/紫色）
• 交互式弹出窗口：一键访问，并可分离为浮动窗口
• 实时状态指示器：来自 status.claude.com 的实时 Claude 系统状态
• 多语言支持：支持 9 种语言（英语、西班牙语、法语、德语、意大利语、葡萄牙语、日语、韩语、简体中文）
• 自适应浅色/深色模式的颜色方案

自动化与智能化

• 自动开始会话：当使用量重置为 0% 时，自动初始化新会话
• 自动切换个人资料：在会话达到限制时自动切换到下一个个人资料
• 唤醒后刷新：唤醒后自动刷新，并带有防抖功能
• 智能通知：在 75%、90%、95% 设置阈值提醒，还可自定义阈值并选择提示音
• 网络监控：自动检测连接变化，并处理离线情况
• 登录时启动：系统级自动启动选项
• 可配置的刷新频率：可设置 5 至 120 秒的刷新间隔
• 会话重置和自动开始确认信息

开发者集成

• Claude Code 终端状态行：在你的终端中实时显示使用情况
• 可自定义组件：目录、git 分支、模型名称、上下文窗口、个人资料名称、使用百分比、进度条、节奏标记、重置计时器
• 3 种颜色模式：多色、灰度、单色（自定义十六进制），用于状态行
• 节奏标记：进度条上的 6 级彩色标记，显示预计的使用节奏
• 标签切换：可显示或隐藏“Ctx:”、“Usage:”、“Reset:”前缀
• 24 小时制：可选的 24 小时制重置时间
• 终端匹配的预览效果，使用与 ANSI 兼容的颜色
• 通过使用缓存实现即时渲染（无启动延迟）
• 一键自动安装
• 应用更改前的实时预览

安全与隐私

• macOS 钥匙链存储：会话密钥存储在 macOS 钥匙链中（最安全的方式）
• 自动迁移：无缝迁移到旧的存储方式
• Apple 代码签名：经 Apple 验证，增强安全性和信任度
• 高级错误处理：专业的错误处理系统，配合用户友好的恢复机制
• 强大的验证功能：会话密钥和 API 端点验证
• 本地存储，不进行云端同步
• 无遥测或追踪
• 仅通过 HTTPS 与 Claude API 通信

高级功能

• 多屏幕支持
• 首次运行引导式设置向导
• 基于协议的模块化架构
• 使用 App Groups 实现持久化设置
• 全面的测试覆盖

---

使用说明

菜单栏界面

点击菜单栏图标即可访问：

• 会话使用情况：5 小时滚动窗口的百分比及重置时间
• 每周使用情况：所有模型的总体周使用量
• Opus 使用情况：每周的 Opus 特定使用量（如适用）
• API 费用：月度费用，附带每日图表和按密钥细分的费用明细（若已配置控制台）
• 快速操作：刷新和设置

设置

可通过菜单栏弹出窗口中的“设置”按钮访问全面的设置。该应用采用现代化的侧边栏界面，配有个人资料切换器和分类清晰的选项卡：

个人资料专用设置

个人资料切换器（侧边栏）

• 快速选择个人资料：下拉菜单可即时切换不同个人资料
• 个人资料徽章：Claude.ai 🔵 和 CLI ✅ 凭证的可视化标识
• 当前活动个人资料显示：显示当前选定的个人资料

Claude.AI（凭证）

配置您的 Claude.ai 个人账户：

• 浏览器登录：通过嵌入式浏览器登录，自动提取会话密钥（v3.0.2+）
• 三步设置向导：引导式会话密钥配置
  • 非破坏性连接测试
  • 可视化组织选择器
  • 包含预览的配置摘要
• 手动输入密钥：高级选项，在展开组中直接输入会话密钥
• 智能更新：重新输入相同密钥时，组织信息保持不变

API 控制台（凭证）

配置 API 控制台使用情况跟踪：

• 浏览器登录：通过嵌入式浏览器登录 Anthropic 控制台（v3.0.2+）
• API 会话密钥：设置您的 API 认证密钥（手动备用）
• 组织 ID：为 API 跟踪配置组织
• 双重跟踪：同时监控网页和 API 使用情况
• API 账单：查看 API 控制台消费、预付积分及每月费用明细
• 会话密钥有效期：可视化状态指示器，显示您的会话密钥何时过期

CLI 账户（凭证）

同步 Claude Code CLI 凭证：

• 一键同步：将当前登录的 Claude Code 账户复制到个人资料中
• 凭证显示：查看遮蔽后的访问令牌和订阅类型
• 自动切换：更换个人资料时，凭据会自动更新
• 取消同步：从个人资料中解除 CLI 账户关联

外观

按个人资料自定义菜单栏图标：

• 图标样式选择：从 5 种不同的显示模式中选择
  • 电池样式（经典带填充的指示器）
  • 进度条（带有百分比的水平条）
  • 仅百分比（纯文本极简风格）
  • 图标加进度条（Claude 图标 + 进度）
  • 紧凑型（节省空间）
• 3 种颜色模式：多色（基于阈值）、灰度（适应外观）或单色（自定义十六进制）
• 节奏标记：进度条上的彩色时间标记，显示预计使用节奏（6 层）
• 百分比显示模式：在已用百分比与剩余百分比之间切换
  • 显示“已使用 75%”或“还剩 25%”——由您选择
  • 颜色编码会自动调整（剩余多时为绿色，剩余少时为红色）
  • 帮助您关注预算剩余而非已花费的预算
• 实时预览：应用更改前即可实时查看效果

通用（个人资料设置）

按个人资料配置行为：

• 刷新间隔：配置自动刷新频率（5–300 秒）
• 自动启动会话：启用或禁用重置时自动初始化会话
• 模型选择：使用成本效益最高的可用模型
• 通知：按个人资料设置阈值警报（75%、90%、95%）+ 自定义阈值及声音选择器

应用程序范围设置

管理个人资料

创建并管理多个个人资料：

• 创建个人资料：添加新个人资料，并自动生成有趣的名字
• 重命名个人资料：自定义个人资料名称
• 删除个人资料：移除未使用的个人资料（至少保留一个）
• 个人资料列表：查看所有个人资料及其凭证状态指示器
• 显示模式切换：在单人模式和多人模式之间切换
  • 单人模式：仅在菜单栏中显示当前活动个人资料
  • 多人模式：在菜单栏中同时显示所有个人资料
• 自动切换个人资料：当会话限额达到时，自动切换到下一个可用个人资料

语言

应用程序语言偏好：

• 语言选择：从 9 种支持的语言中选择
• 实时更新：更改语言后界面立即更新
• 支持语言：英语、西班牙语、法语、德语、意大利语、葡萄牙语、日语、韩语、简体中文

Claude Code（状态行）

终端集成（全应用范围）：

• 组件选择：选择要显示的内容（目录、分支、模型名称、上下文窗口、个人资料名称、使用情况、进度条、节奏标记、重置时间）
• 颜色模式：多色、灰度或单色，并提供自定义十六进制选择器
• 节奏标记：进度条上显示的 6 层彩色标记，指示预计使用节奏
• 标签开关：显示/隐藏“Ctx:”、“Usage:”、“Reset:”等前缀，以实现紧凑显示
• 24 小时制：可选的 24 小时制重置时间
• 实时预览：与终端匹配的预览，采用 ANSI 等效颜色
• 一键安装：自动脚本安装至 ~/.claude/
• 自动更新：切换个人资料时状态行会自动更新
• 使用情况缓存：通过缓存的使用数据实现 CLI 的即时渲染
• 详细设置请参阅【Claude Code 集成】章节

更新

自动更新配置：

• 自动检查更新：配置检查更新的频率
• 更新通知：在有新版本可用时收到通知
• 一键安装：只需单击即可下载并安装更新
• 发布说明：查看每次更新的新内容

关于

应用程序信息：

• 版本信息：当前应用版本
• 致谢：贡献者及鸣谢
• 链接：GitHub 仓库、问题追踪器、文档

Claude Code 集成

通过 Claude Code 状态行集成，将实时 Claude 使用情况监控直接引入您的终端！无需离开开发流程，即可显示当前使用百分比、模型名称、上下文窗口、个人资料名称、Git 分支和工作目录。

什么是 Claude Code？

Claude Code 是 Anthropic 官方提供的 CLI 工具，用于直接从终端与 Claude AI 交互。状态行功能允许您在终端窗口底部显示自定义信息。

设置说明

先决条件

1. 已安装 Claude Code：请从 claude.com/claude-code 下载。
2. 会话密钥已配置：必须在“个人使用”选项卡中手动配置（Claude Code 的 OAuth 不适用于状态栏——它需要直接使用会话密钥）。

安装步骤

1. 打开 Claude 使用跟踪器设置

   • 点击菜单栏图标
   • 点击“设置”
   • 导航到“Claude Code”选项卡

2. 选择组件

   • 开启或关闭您希望显示的组件：
     • 目录名称：显示当前工作目录
     • Git 分支：以 ⎇ 图标显示当前分支
     • 模型名称：显示当前模型（Opus、Sonnet）
     • 配置文件名称：显示活动配置文件名称
     • 上下文窗口：以百分比或令牌数量显示上下文使用情况
     • 使用统计：以颜色编码显示会话百分比
     • 进度条：可视化的 10 段指示器（启用使用统计时可选）
     • 节奏标记：进度条上根据经过时间位置显示的彩色 ┃（6 层节奏颜色）
     • 重置时间：您的会话何时重置（12 小时或 24 小时格式）
   • 颜色模式：选择多色、灰度或单色
   • 标签切换：显示或隐藏“Ctx:”、“Usage:”、“Reset:”前缀

3. 预览状态栏

   • 实时预览将准确展示其在终端中的显示效果，采用与终端匹配的 ANSI 颜色。
   • 示例：claude-usage │ ⎇ main │ Opus │ Work │ Ctx: 48% │ Usage: 25% ▓▓┃░░░░░░░ → Reset: 3:45 PM

4. 应用配置

   • 点击“应用”按钮
   • 脚本将被安装到 ~/.claude/
   • Claude Code 的 settings.json 文件将自动更新。

5. 重启 Claude Code

   • 关闭并重新打开您的 Claude Code 终端
   • 状态栏将出现在终端窗口底部。

安装内容

设置过程会自动创建：

• ~/.claude/fetch-claude-usage.swift：用于从 Claude API 获取使用数据的 Swift 脚本
• ~/.claude/statusline-command.sh：用于构建状态栏显示的 Bash 脚本
• ~/.claude/statusline-config.txt：包含您组件偏好设置的配置文件
• ~/.claude/settings.json：更新了状态栏命令（如果不存在则创建）

所有脚本均设置了安全权限（755），且仅读取您现有的会话密钥文件。

自定义

可用组件

组件	描述	示例
目录	当前目录名称	claude-usage
Git 分支	活动 Git 分支	⎇ main
模型	当前模型名称	Opus
配置文件	活动配置文件名称	Work
上下文	上下文窗口使用情况	Ctx: 48% 或 96K
使用	会话百分比	Usage: 25% 或 25%
进度条	10 段可视化指示器	▓▓░░░░░░░░
节奏标记	根据经过时间位置的彩色标记	▓▓┃░░░░░░░
重置时间	会话何时重置	→ Reset: 3:45 PM 或 → 15:45

颜色编码

使用条采用 10 级渐变颜色：

• 0–10%：深绿色
• 11–30%：绿色系
• 31–50%：黄绿色过渡到橄榄色
• 51–70%：黄色至橙色
• 71–90%：深橙色至红色
• 91–100%：深红色

节奏标记基于预计期末使用情况，采用 6 层系统：

• 舒适（预计 <50%）：绿色
• 正常（50–75%）：蓝绿色
• 警戒（75–90%）：黄色
• 紧张（90–100%）：橙色
• 危险（100–120%）：红色
• 失控（>120%）：紫色

颜色模式（适用于菜单栏和状态栏）：

• 多色：完整调色板（默认）
• 灰度：无颜色，适应系统主题
• 单色：所有元素使用您自定义的十六进制颜色。

禁用状态栏

要移除状态栏：

1. 打开 Claude 使用跟踪器设置 → Claude Code 选项卡
2. 点击“重置”按钮
3. 重启 Claude Code

这将移除状态栏配置，但保留脚本以便于再次启用。

故障排除

状态栏未显示

1. 确认 Claude Code 已安装并正常运行
2. 检查是否在应用设置后重启了 Claude Code
3. 确保“常规设置”选项卡中的会话密钥有效
4. 检查 ~/.claude/settings.json 是否存在，并包含状态栏配置。

显示“Usage: ~”

这表示 Swift 脚本无法获取使用数据：

• 确认您的会话密钥有效
• 检查 ~/.claude-session-key 是否存在
• 确保您已连接互联网
• 尝试从 claude.ai 刷新会话密钥。

权限问题

如果脚本无法执行：

chmod 755 ~/.claude/fetch-claude-usage.swift
chmod 755 ~/.claude/statusline-command.sh

状态栏示例

启用所有组件（多色模式）：

my-project │ ⎇ feature/new-ui │ Opus │ Work │ Ctx: 48% │ Usage: 47% ▓▓▓▓┃░░░░░ → Reset: 4:15 PM

简洁版（隐藏标签，24 小时制）：

my-project │ ⎇ develop │ 12% ▓┃░░░░░░░░ → 16:15

仅显示模型和上下文：

Sonnet │ Ctx: 96K │ Usage: 25%

架构

技术栈

• 语言：Swift 5.0+
• UI 框架：SwiftUI 5.0+
• 平台：macOS 14.0+（Sonoma）
• 架构：MVVM 结合面向协议的设计
• 存储：UserDefaults 与 App Groups
• 网络：URLSession 结合 async/await
• 设计模式：协调者模式、基于协议的服务、模块化组件。

API 集成

该应用程序集成了多个 Claude API 端点，以实现全面的使用跟踪：

Web 使用端点

GET https://claude.ai/api/organizations/{org_id}/usage

认证：来自 claude.ai 的会话 Cookie（sessionKey）

响应结构：

• five_hour：5 小时会话使用数据
  • utilization_pct：使用百分比（0–100）
  • reset_at：下次重置的 ISO 8601 时间戳
• seven_day：所有模型的周使用情况
  • utilization_pct：周使用百分比
• seven_day_opus：Opus 特定的周使用情况
  • utilization_pct：Opus 周使用百分比
• extra_usage：Claude Extra 费用跟踪（如适用）
  • current_spending：已花费金额
  • budget_limit：允许的最大支出

API 控制台端点

GET https://api.anthropic.com/v1/organization/{org_id}/usage

认证：API 密钥（x-api-key 头部）

响应结构：

• API 控制台使用统计信息
• 计费信息
• 速率限制和配额

双重跟踪

该应用可以同时监控网页端（claude.ai）和 API 控制台的使用情况，从而为您提供跨所有访问方式的 Claude 使用情况的完整视图。

安全性

• macOS 钥匙串：会话密钥安全存储在 macOS 钥匙串中（最安全的存储方式）
• 自动迁移：v2.0 及以上版本会自动将会话密钥从旧的存储方式迁移到钥匙串
• Apple 代码签名：使用 Apple 开发者证书进行官方签名，确保应用的真实性
• 安全更新：通过 HTTPS 提供自动更新，并进行代码签名验证
• 无云端同步：所有数据均保留在本地设备上
• 无遥测：不收集任何跟踪或分析数据
• 高级错误处理：强大的错误处理系统，提供友好的恢复机制
• 会话密钥验证：对 API 凭证进行全面验证
• 网络：仅通过 HTTPS 与 claude.ai 和 Anthropic API 进行通信

故障排除

应用无法连接

1. 确认您的会话密钥有效。
2. 检查您是否已在浏览器中登录 claude.ai。
3. 尝试重新获取一个新鲜的会话密钥。
4. 确保您有活跃的互联网连接。

403 权限错误

如果出现“未授权”或 403 错误：

1. 打开设置 → 个人使用。
2. 使用三步向导重新配置：
   • 测试您的会话密钥。
   • 选择正确的组织。
   • 保存配置。
3. 向导会在更新密钥时保留您选择的组织。

菜单栏图标显示为零

如果图标在刷新时短暂地变为零：

• 此问题已在 v2.1.0 及以上版本中修复。
• 请更新到最新版本以获得流畅的刷新体验。
• 旧数据现在会一直显示，直到新数据到达。

菜单栏图标未显示

1. 检查系统设置 → 桌面与菜单栏 → 菜单栏。
2. 重启应用程序。
3. 查看 Console.app 中是否有错误信息。

会话密钥过期

会话密钥可能会在一段时间后过期。您将在过期前 24 小时收到通知（v3.0.2 及以上版本）。要刷新：

1. 前往设置 → 个人使用（或 API 控制台）。
2. 点击“登录 Claude.ai”（或“登录 Anthropic 控制台”），通过内置浏览器重新认证。
3. 或展开“高级：手动会话密钥”，手动粘贴新的密钥。

更新不起作用

如果自动更新无法正常工作：

1. 检查设置 → 更新，确保已启用自动检查。
2. 确认您正在运行 v2.0.0 或更高版本（较早版本没有自动更新功能）。
3. 检查您的互联网连接。
4. 如有必要，可从 GitHub 手动下载最新版本。

贡献者

本项目是为社区打造的——欢迎所有人参与！

特别感谢

非常感谢所有提交过拉取请求的开发者。v3.0.0 中的许多功能都受到社区 PR 的启发，或者直接移植自这些 PR，但由于本次发布规模较大、冲突较多，未能直接合并。正是你们的代码、想法和努力促成了这次发布：

参与贡献

我们欢迎任何形式的贡献！请随时提交拉取请求。对于重大更改，请先打开一个问题来讨论您希望做出的修改。

开发环境设置

1. 分支仓库。
2. 创建您的功能分支 (git checkout -b feature/AmazingFeature)。
3. 提交您的更改 (git commit -m '添加一些 AmazingFeature')。
4. 推送到该分支 (git push origin feature/AmazingFeature)。
5. 打开拉取请求。

代码风格

• 遵循 Swift API 设计指南。
• 使用 SwiftUI 最佳实践。
• 维持 MVVM 架构。
• 为复杂逻辑添加注释。
• 编写描述性的提交信息。

许可证

本项目采用 MIT 许可证授权——详情请参阅 LICENSE 文件。

致谢

• 使用 Swift 和 SwiftUI 构建。
• 专为 macOS Sonoma 及更高版本设计。
• 使用 Claude AI 的用量 API。
• 灵感来源于对更好用量可视化的需求。

免责声明

本应用与 Anthropic PBC 无关联、未获其认可或赞助。Claude 是 Anthropic PBC 的商标。本工具为独立第三方开发，用于个人用量监控。

AI 透明度

本项目采用 AI 辅助的工作流程开发（主要通过 Happy 使用 Claude Code）。我们相信人类开发者与 AI 工具之间应保持透明的合作关系。

---

Claude Usage Tracker 快速上手指南

Claude Usage Tracker 是一款专为 macOS 设计的原生菜单栏应用，用于实时监控 Claude AI 的使用限额（会话窗口、周限额及 API 消耗）。它支持多账号管理、终端状态行集成及自动化通知。

环境准备

在开始之前，请确保满足以下条件：

• 操作系统：macOS 14.0 (Sonoma) 或更高版本。
  • 检查方法：点击苹果菜单  > 关于本机。
• 账号要求：拥有有效的 Claude AI 账号 (claude.ai)。
• 认证方式（任选其一）：
  1. 推荐：已安装并登录 Claude Code CLI（应用可自动同步凭证）。
  2. 内置浏览器：通过应用内嵌浏览器直接登录（v3.0.2+ 支持）。
  3. 手动配置：从浏览器中提取 sessionKey。

注意：若需使用终端状态行（Statusline）功能，即使使用了 Claude Code OAuth，仍需手动配置 Session Key。

安装步骤

方式一：Homebrew 安装（推荐）

这是最简便的安装方式，支持自动更新。

# 添加仓库并安装
brew tap hamed-elfayome/claude-usage
brew install --cask claude-usage-tracker

更新应用：

brew upgrade --cask claude-usage-tracker

卸载应用：

brew uninstall --cask claude-usage-tracker

方式二：直接下载安装

1. 下载最新安装包：Claude-Usage.zip
2. 解压下载的 .zip 文件。
3. 将 Claude Usage.app 拖入 应用程序 (Applications) 文件夹。
4. 双击运行即可。

说明：v2.0.0+ 版本已使用 Apple 开发者证书签名，无需绕过安全限制即可直接运行。

方式三：源码构建

git clone https://github.com/hamed-elfayome/Claude-Usage-Tracker.git
cd Claude-Usage-Tracker
open "Claude Usage.xcodeproj"
# 在 Xcode 中按 ⌘R 构建并运行

基本使用

场景 A：自动配置（适用于 Claude Code 用户）

如果你已安装并登录了 Claude Code CLI，应用将自动检测凭证，无需额外操作。

1. 确保终端中已执行 claude login 并登录成功。
2. 启动 Claude Usage Tracker。
3. 点击菜单栏图标，即可立即看到使用统计信息。

场景 B：内置浏览器登录（适用于普通网页用户）

如果你未使用 CLI，可通过应用内嵌浏览器直接登录。

1. 点击菜单栏图标，选择 Settings (设置)。
2. 进入 Personal Usage 标签页。
3. 点击 Sign in to Claude.ai，弹出内置浏览器窗口。
4. 输入账号密码或使用 Google SSO 登录。
5. 登录成功后，应用会自动提取 Session Key 并验证，选择对应的组织即可保存。

场景 C：手动配置 Session Key

如果需要手动提取凭证：

第一步：获取 Session Key

1. 在浏览器访问 claude.ai 并登录。
2. 打开开发者工具：
   • Chrome/Edge: 按 F12 或 Cmd+Option+I
   • Safari: 需在偏好设置中开启“开发”菜单，然后按 Cmd+Option+I
3. 进入 Application (Chrome/Edge) 或 Storage (Firefox) 标签页。
4. 展开 Cookies -> 选择 https://claude.ai。
5. 找到名为 sessionKey 的项，复制其值（格式通常为 sk-ant-sid01-...）。

第二步：填入应用

1. 点击菜单栏图标 > Settings > Personal Usage。
2. 展开 Advanced: Manual Session Key。
3. 粘贴刚才复制的 Key，点击 Test Connection。
4. 选择组织并点击 Save Configuration。

后续优化建议

• 自定义图标：前往 Settings > Appearance 切换图标风格（支持 5 种样式及多种颜色模式）。
• 开启通知：在 Settings > Notifications 中设置用量阈值提醒。
• 终端集成：在 Settings > Claude Code 中配置终端状态行，可在命令行实时显示模型、上下文及用量信息。
• 多账号管理：支持创建无限数量的配置文件（Profile），可在菜单栏同时监控多个账号，并支持快捷键快速切换。