Skip to content
BSWEN
Blog

How to Monitor Claude Pro and Max Rate Limits with Claude HUD

Cowrie
Cowrie
Dev @ Bswen

I was in the middle of a long coding session with Claude when suddenly I hit a rate limit. No warning, just stopped working. Had to wait hours before I could continue. That’s when I realized I needed a way to track my usage before hitting the wall.

Claude Pro, Max, and Team subscriptions have two rate limit windows: a 5-hour window that resets multiple times per day, and a 7-day window that resets weekly. Hitting 100% on either means you’re stuck waiting. Claude HUD solves this by showing your usage in real-time.

The Display Format

Claude HUD shows usage right in the status line alongside your context bar. Here’s what it looks like during normal usage:

Normal usage display
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)

The progress bar gives you a quick visual. ██░░░░░░░░ means 2 out of 10 blocks filled. The time shown (1h 30m / 5h) tells you exactly how long until the 5-hour window resets.

When your 7-day usage gets high, a second indicator appears:

High 7-day usage warning
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h) | ██████████ 85% (2d / 7d)

The 7-day percentage only shows when you’re above 80% by default. This keeps the display clean when you have plenty of room, but warns you when you’re getting close to the limit.

How It Works

Claude HUD fetches your usage data from Anthropic’s OAuth usage API. The key points:

  1. OAuth required - You need to be logged in via Claude Code’s OAuth flow (not using an API key)
  2. Pro/Max/Team only - API users don’t have rate limits (they pay per token), so there’s nothing to display
  3. Smart caching - Results cache for 60 seconds on success, 15 seconds on failure, avoiding excessive API calls

The data structure behind the display looks like this:

Usage data structure (src/types.ts)
export interface UsageData {
  planName: string | null;  // 'Max', 'Pro', or null for API users
  fiveHour: number | null;  // 0-100 percentage, null if unavailable
  sevenDay: number | null;  // 0-100 percentage, null if unavailable
  fiveHourResetAt: Date | null;
  sevenDayResetAt: Date | null;
}

Configuration Options

You can customize the display behavior in your settings:

  • display.showUsage - Enable or disable the usage display entirely (default: true)
  • display.usageBarEnabled - Toggle between bar style and plain text (default: true)
  • display.sevenDayThreshold - When to show the 7-day indicator (default: 80)

I kept the defaults and it works well. The bar style is more useful than plain text because you can glance at it and immediately know if you’re in trouble.

When You Hit the Limit

If you do reach 100%, the display changes to show the reset time:

Rate limit reached
Context █████░░░░░ 45% │ Usage ██████████ 100% (reset in 2h)

At this point you know exactly how long to wait. No more guessing or refreshing hoping it will work.

Requirements and Limitations

For the usage display to work, you need:

  1. A Claude Pro, Max, or Team subscription
  2. Logged in via OAuth (created automatically when you log in with Claude Code)
  3. Not using a custom ANTHROPIC_BASE_URL environment variable

If you’re using AWS Bedrock, you’ll see Bedrock in the status line and the usage limits are hidden (Bedrock has its own pricing model). For proxy users, make sure to set the HTTPS_PROXY environment variable.

API users won’t see any usage display because they don’t have rate limits - they pay per token instead. This is actually a feature, not a bug: rate limits are a subscription thing.

Why This Matters

Before using Claude HUD, I had no visibility into my usage. I’d be working along and suddenly get blocked. Now I can see when I’m getting close to limits and either pace myself or plan around the reset time.

The 7-day limit is the tricky one. You might not hit the 5-hour limit often, but the 7-day limit can sneak up on you during a heavy week of development. Having that 85% warning gives you time to adjust before it becomes a problem.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: