claude-code-usage

Claude Code Usage 是一个检查 Claude Code OAuth API 使用限额的命令行工具，可查看会话（5 小时）与每周（7 天）两个窗口的配额消耗情况。

用途用于查询 Claude Code 的 OAuth 用量限额，回答当前还剩多少额度、是否接近速率限制、配额何时重置等问题，帮助用户在工作中避免因额度耗尽而中断。

主要能力

会话限额（5 小时窗口）：短期速率限制的用量展示。
每周限额（7 天窗口）：长期速率限制的用量展示。
智能缓存：默认 60 秒缓存，避免频繁请求 API，可通过 --cache-ttl 自定义，也可用 --fresh 强制刷新。
输出格式：默认文本格式，包含进度条、表情符号与颜色状态；--json 输出机器可读的 JSON。
状态指示：绿色 0-50% 为健康，黄色 51-80% 为中等，红色 81-100% 为高/临界。
自动监控：提供会话刷新提醒与重置检测监控两种方案。

使用方式快速开始：

cd {baseDir} ./scripts/claude-usage.sh

默认显示缓存用量（若缓存仍新鲜）。强制从 API 刷新：

./scripts/claude-usage.sh --fresh

JSON 输出：

./scripts/claude-usage.sh --json

自定义缓存 TTL：

./scripts/claude-usage.sh --cache-ttl 300

文本输出示例：

🦞 Claude Code Usage

⏱️ Session (5h): 🟢 ████░░░░░░ 40% Resets in: 2h 15m

📅 Weekly (7d): 🟡 ██████░░░░ 60% Resets in: 3d 8h

JSON 输出示例：

{
  "session": {
    "utilization": 40,
    "resets_in": "2h 15m",
    "resets_at": "2026-01-19T22:15:00Z"
  },
  "weekly": {
    "utilization": 60,
    "resets_in": "3d 8h",
    "resets_at": "2026-01-22T04:00:00Z"
  },
  "cached_at": "2026-01-19T20:00:00Z"
}

缓存的默认位置为 /tmp/claude-usage-cache，TTL 60 秒。可通过环境变量覆盖：

CACHE_FILE=/tmp/my-cache CACHE_TTL=300 ./scripts/claude-usage.sh

常见用法示例：

开始工作前检查用量：

./scripts/claude-usage.sh --fresh

集成到状态栏：

usage=$(./scripts/claude-usage.sh | grep "Session" | awk '{print $NF}') echo "Session: $usage"

获取 JSON 用于监控：

./scripts/claude-usage.sh --json | jq '.session.utilization'

自动监控方案一：会话刷新提醒（推荐）。在 5 小时会话配额刷新时准确收到通知：

./scripts/session-reminder.sh

该命令创建一条自我调度的 cron 任务链：检查当前会话过期时间，为下次刷新时间安排提醒，通知时附带当前用量统计，并自动移除自身（由新 cron 接替）。通知示例：

🔄 Claude Code Session Status

⏱️ Current usage: 44% ⏰ Next refresh: 2h 15m

Your 5-hour quota will reset soon! 🦞

✅ Next reminder scheduled for: Jan 22 at 01:22 AM

方案二：重置检测监控。通过轮询用量在配额重置时自动通知：

测试一次

./scripts/monitor-usage.sh

设置自动监控（每 30 分钟运行一次）

./scripts/setup-monitoring.sh

也可通过 ThinkFleetBot 直接添加：

thinkfleetbot cron add --cron "*/30 * * * *"
--message "cd /Users/ali/thinkfleet/skills/claude-code-usage && ./scripts/monitor-usage.sh"
--name "Claude Code Usage Monitor"
--session isolated --deliver --channel telegram

重置检测的工作方式：每 30 分钟（可配置）检查一次用量，当用量显著下降（超过 10% 或低于 5%）时判定为重置，并通过 Telegram 发送通知，状态记录在 /tmp/claude-usage-state.json。可自定义检查间隔与状态文件位置：

thinkfleetbot cron add --cron "*/15 * * * *" ... # 每 15 分钟 thinkfleetbot cron add --cron "0 * * * *" ... # 每小时 STATE_FILE=/path/to/state.json ./scripts/monitor-usage.sh

两种监控方式对比：会话刷新提醒精确到分钟、API 调用少、在重置时立即通知、自我调度；重置检测监控约 30 分钟窗口、每次检查都调用 API、最多延迟 30 分钟、cron 持续运行。推荐使用会话刷新提醒以获得精确实时的通知。

工作原理从系统钥匙串获取 OAuth token，使用 OAuth bearer token 请求 api.anthropic.com/api/oauth/usage，解析 five_hour 与 seven_day 利用率指标，计算重置剩余时间，并以进度条与状态指示格式化输出，结果缓存 60 秒（可配置）。

适用场景

在开始编码前确认剩余额度，合理安排工作节奏。
将用量嵌入状态栏或仪表盘。
通过 JSON 输出接入自定义监控流程。
通过定时任务在配额刷新或重置时获得提醒。

限制与要求

macOS：使用 Keychain 访问 Claude Code 凭据；Linux：使用 secret-tool 存储凭据。
需要已安装并完成认证的 Claude Code CLI。
Linux 用户需安装 libsecret 以支持凭据存储：Debian/Ubuntu 使用 sudo apt install libsecret-tools，Fedora/RHEL 使用 sudo dnf install libsecret。
若未找到凭据，请确认已安装 Claude Code CLI 并完成认证，可先运行 claude 触发 OAuth 流程。
若 API 请求失败，请检查网络连接、确认 OAuth token 未过期，或使用 --fresh 强制发起新请求。
监控依赖 cron 与通知渠道（示例中为 Telegram），相关配置需自行提供。

技能介绍

测试一次

设置自动监控（每 30 分钟运行一次）