Claude Code Usage

Check your Claude Code OAuth API usage limits for both session (5-hour) and weekly (7-day) windows.

Quick Start

CODEBLOCK0

Usage

CODEBLOCK1

Output

Text format (default):
CODEBLOCK2

JSON format (--json):
CODEBLOCK3

Features

- 📊 Session limit (5-hour window) - Short-term rate limit
📅 Weekly limit (7-day window) - Long-term rate limit
⚡ Smart caching - 60-second cache to avoid API spam
🎨 Beautiful output - Progress bars, emojis, color-coded status
🔄 Force refresh - --fresh flag to bypass cache
📤 JSON output - Machine-readable format
🔔 Automated monitoring - Get notified when quotas reset

Status Indicators

- 🟢 Green - 0-50% usage (healthy)
🟡 Yellow - 51-80% usage (moderate)
🔴 Red - 81-100% usage (high/critical)

Requirements

- macOS: Uses Keychain to access Claude Code credentials
Linux: Uses secret-tool for credential storage
Credentials: Must have Claude Code CLI authenticated

How It Works

1. Retrieves OAuth token from system keychain
Queries api.anthropic.com/api/oauth/usage with OAuth bearer token
Parses five_hour and seven_day utilization metrics
Calculates time remaining until reset
Formats output with progress bars and status indicators
Caches result for 60 seconds (configurable)

Cache

Default cache: /tmp/claude-usage-cache (60s TTL)

Override:
CODEBLOCK4

Examples

Check usage before starting work:
CODEBLOCK5

Integrate with statusline:
CODEBLOCK6

Get JSON for monitoring:
CODEBLOCK7

Automated Monitoring

Session Refresh Reminders (Recommended)

Get notified exactly when your 5-hour session quota refreshes!

Quick Setup:
CODEBLOCK8

This creates a self-scheduling chain of cron jobs that:

1. Checks your current session expiry time
Schedules the next reminder for when your session refreshes
Notifies you with current usage stats
Auto-removes itself (the new cron takes over)

What You'll Get:
CODEBLOCK9

How It Works:

- Each reminder runs claude-usage.sh to find the exact session reset time
Schedules a one-time cron for that exact moment
Repeats every 5 hours automatically
Self-correcting if session times ever drift

Benefits:

- ✅ Accurate to the minute
✅ No manual scheduling needed
✅ Adapts to your actual usage patterns
✅ Minimal API calls (only when needed)

Reset Detection Monitor (Alternative)

Get automatic notifications when your Claude Code quotas reset by polling usage.

Quick Setup:
CODEBLOCK10

Or add via Clawdbot directly:
CODEBLOCK11

What You'll Get:
CODEBLOCK12

How It Works:

1. Monitors usage every 30 minutes (configurable)
Detects resets when usage drops significantly (>10% or <5%)
Sends notifications via Telegram when resets occur
Tracks state in INLINECODE8

Customization:
CODEBLOCK13

Which Monitoring Method?

Feature	Session Reminder	Reset Detection
Accuracy	✅ Exact minute	~30min window
API calls

Recommendation: Use Session Reminder for precise, real-time notifications.

Troubleshooting

No credentials found:

- Ensure Claude Code CLI is installed and authenticated
Run claude once to trigger OAuth flow

API request failed:

- Check internet connection
Verify OAuth token hasn't expired
Try --fresh to force new request

Linux users:
Install libsecret for credential storage:
CODEBLOCK14

Claude Code 使用量

检查您的 Claude Code OAuth API 使用限制，包括会话（5小时）和每周（7天）时间窗口。

快速开始

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

使用方法

bash

默认：显示缓存的使用量（如果数据较新）

./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 使用量

⏱️ 会话（5小时）：🟢 ████░░░░░░ 40%
重置时间：2小时15分钟后

📅 每周（7天）：🟡 ██████░░░░ 60%
重置时间：3天8小时后

JSON 格式（--json）：
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
}

功能特性

- 📊 会话限制（5小时窗口）- 短期速率限制
📅 每周限制（7天窗口）- 长期速率限制
⚡ 智能缓存 - 60秒缓存，避免频繁调用 API
🎨 美观输出 - 进度条、表情符号、颜色编码状态
🔄 强制刷新 - 使用 --fresh 参数绕过缓存
📤 JSON 输出 - 机器可读格式
🔔 自动监控 - 配额重置时收到通知

状态指示器

- 🟢 绿色 - 0-50% 使用量（健康）
🟡 黄色 - 51-80% 使用量（中等）
🔴 红色 - 81-100% 使用量（高/临界）

系统要求

- macOS：使用钥匙串访问 Claude Code 凭据
Linux：使用 secret-tool 存储凭据
凭据：必须已认证 Claude Code CLI

工作原理

1. 从系统钥匙串中检索 OAuth 令牌
使用 OAuth Bearer 令牌查询 api.anthropic.com/api/oauth/usage
解析 fivehour 和 sevenday 使用率指标
计算距离重置的剩余时间
使用进度条和状态指示器格式化输出
将结果缓存 60 秒（可配置）

缓存

默认缓存：/tmp/claude-usage-cache（60秒 TTL）

覆盖设置：
bash
CACHEFILE=/tmp/my-cache CACHETTL=300 ./scripts/claude-usage.sh

示例

开始工作前检查使用量：
bash
./scripts/claude-usage.sh --fresh

集成到状态栏：
bash
usage=$(./scripts/claude-usage.sh | grep Session | awk {print $NF})
echo 会话：$usage

获取 JSON 用于监控：
bash
./scripts/claude-usage.sh --json | jq .session.utilization

自动监控

会话刷新提醒（推荐）

在您的 5 小时会话配额刷新时立即收到通知！

快速设置：
bash
./scripts/session-reminder.sh

这将创建一个自调度链的 cron 任务，能够：

1. 检查当前会话到期时间
在会话刷新时安排下一次提醒
使用当前使用量统计数据通知您
自动移除自身（新 cron 任务接替）

您将收到：

🔄 Claude Code 会话状态

⏱️ 当前使用量：44%
⏰ 下次刷新：2小时15分钟后

您的 5 小时配额即将重置！🦞

✅ 下次提醒已安排：1月22日 01:22

工作原理：

- 每次提醒运行 claude-usage.sh 查找确切的会话重置时间
在该确切时刻安排一次性 cron 任务
每 5 小时自动重复
如果会话时间发生偏移，会自动修正

优势：

- ✅ 精确到分钟
✅ 无需手动调度
✅ 适应您的实际使用模式
✅ 最少的 API 调用（仅在需要时）

重置检测监控（备选方案）

通过轮询使用量，在 Claude Code 配额重置时自动接收通知。

快速设置：
bash

测试一次

./scripts/monitor-usage.sh

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

./scripts/setup-monitoring.sh

或直接通过 Clawdbot 添加：
bash

每 30 分钟检查一次

clawdbot cron add --cron /30 * \
--message cd /Users/ali/clawd/skills/claude-code-usage && ./scripts/monitor-usage.sh \
--name Claude Code 使用量监控 \
--session isolated --deliver --channel telegram

您将收到：

🎉 Claude Code 会话已重置！

⏱️ 您的 5 小时配额已重置
📊 使用量：2%
⏰ 下次重置：4小时58分钟后

可用配额已刷新！🦞

工作原理：

1. 每 30 分钟监控使用量（可配置）
当使用量显著下降时（>10% 或 <5%）检测重置
重置发生时通过 Telegram 发送通知
在 /tmp/claude-usage-state.json 中跟踪状态

自定义设置：
bash

更改检查间隔

clawdbot cron add --cron /15 * ... # 每 15 分钟
clawdbot cron add --cron 0 ... # 每小时

自定义状态文件位置

STATE_FILE=/path/to/state.json ./scripts/monitor-usage.sh

选择哪种监控方式？

功能	会话提醒	重置检测
准确性	✅ 精确到分钟	~30分钟窗口
API 调用

建议： 使用会话提醒获取精确的实时通知。

故障排除

未找到凭据：

- 确保已安装并认证 Claude Code CLI
运行一次 claude 触发 OAuth 流程

API 请求失败：

- 检查网络连接
验证 OAuth 令牌是否已过期
尝试使用 --fresh 强制发起新请求

Linux 用户：
安装 libsecret 用于凭据存储：
bash

Debian/Ubuntu

sudo apt install libsecret-tools

Fedora/RHEL

sudo dnf install libsecret

claude-code-usageClaude代码用量