Episode 7: Usage Limits

Key Takeaway: Know how much subscription quota you have left to avoid being rate-limited at critical moments.

---

7.1 Who Has Usage Limits

Subscription	Has Limits	Notes
Claude Pro	Yes	5-hour rolling window + 7-day window
Claude Max	Yes	Higher limits
Claude Team	Yes	Shared team pool
API users	No	Pay per token used

---

7.2 Usage Display in HUD

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

Info	Meaning
25%	5-hour window 25% used
1h 30m	1.5 hours consumed
5h	Total window length

When 7-day usage exceeds threshold, additional display appears:

Usage ██░░░░░░░░ 25% (1h 30m / 5h) | ██████████ 85% (2d / 7d)

---

7.3 Usage Bar Colors

Color	Meaning
🔵 Blue	Normal
🟣 Purple	Approaching threshold
🔴 Red	Limit reached

---

7.4 Troubleshooting Missing Usage

• Confirm you have a Pro/Max/Team subscription (not API key)
• display.showUsage is not false
• API users have no quota display (pay per token)
• Bedrock/Vertex users manage usage in cloud platform
• Custom ANTHROPIC_BASE_URL skips usage display

---

7.5 Configuring Usage Display

{
  "display": {
    "showUsage": true,
    "usageBarEnabled": true,
    "usageCompact": false,
    "sevenDayThreshold": 80,
    "timeFormat": "relative",
    "showResetLabel": true
  }
}

Config	Description
usageCompact	Short text format, e.g., 5h: 25% (1h 30m)
timeFormat	relative (countdown) / absolute (exact time) / both
sevenDayThreshold	7-day usage display threshold (0 = always show)

---

Next Episode: Episode 8 covers Git status display and tool/Agent/Todo activity lines — configuration and meanings.