claude-code-usage

Overview

Check your Claude Code OAuth API usage limits for both session (5-hour) and weekly (7-day) windows. Get automated session refresh reminders and reset detection monitoring.

Key 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

How It Works

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

Use Cases

• Check usage before starting work
• Integrate with statusline
• Get JSON for monitoring
• Automated session refresh reminders
• Reset detection monitor