Skip to main content
Claude HUD can show your rate limit consumption directly in the HUD alongside the context bar. This is enabled by default for users on a Claude Pro, Max, or Team subscription.

​
Who sees usage

Subscriber typeUsage display
Claude ProShown — 5-hour and 7-day windows
Claude MaxShown — 5-hour and 7-day windows
Claude TeamShown — 5-hour and 7-day windows
API usersNot shown — API billing is pay-per-token, not rate-limited
AWS BedrockNot shown — displays Bedrock label; usage is managed in AWS

​
How it works

Claude HUD reads OAuth credentials from ~/.claude/.credentials.json. These are created automatically when you log in to Claude Code. The credentials are used to call the Anthropic usage API at api.anthropic.com/api/oauth/usage. Two time windows are tracked:
  • 5-hour window — short-term rate limit, resets every 5 hours
  • 7-day window — weekly usage, shown only when above sevenDayThreshold
The API response is cached to avoid hammering the endpoint on every HUD refresh.

​
What you see

Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)
When 7-day usage exceeds the threshold (default 80%): 
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h) | ██████████ 85% (2d / 7d)

​
Configuration options

​
display.showUsage
boolean
default:"true"
Enable or disable the usage display entirely. Set to false to hide usage for all subscriber types.
​
display.usageBarEnabled
boolean
default:"true"
Controls the visual style of the usage display:
  • true — visual bar: ██░░░░░░░░ 25% (1h 30m / 5h)
  • false — text only: 5h: 25% (1h 30m)
​
display.sevenDayThreshold
number
default:"80"
The 7-day usage bar is only shown when your 7-day usage percentage is at or above this value. Set to 0 to always show the 7-day bar. Range: 0–100.
​
display.usageThreshold
number
default:"0"
Minimum usage percentage before the usage bar appears at all. 0 means always show. Range: 0–100.
​
usage.cacheTtlSeconds
number
default:"60"
How many seconds to cache a successful usage API response before fetching fresh data.
​
usage.failureCacheTtlSeconds
number
default:"15"
How many seconds to cache a failed usage API response before retrying. Reduces noise when there is a temporary connectivity issue.

​
Environment variables

​
CLAUDE_HUD_USAGE_TIMEOUT_MS
number
default:"15000"
Timeout in milliseconds for the usage API request. Default is 15000 (15 seconds). Increase this in high-latency environments if usage data is not loading reliably.

​
Proxy support

Claude HUD respects standard proxy environment variables for the usage API request:
VariablePurpose
HTTPS_PROXYProxy for HTTPS requests (recommended)
HTTP_PROXYProxy for HTTP requests
ALL_PROXYProxy for all requests
NO_PROXYComma-separated list of hosts to bypass the proxy
Set the appropriate variable before starting Claude Code: 
export HTTPS_PROXY=https://proxy.example.com:8080
claude

​
Troubleshooting

Usage not showing at all?
  • Confirm you are logged in with a Pro, Max, or Team account — not an API key
  • Check that display.showUsage is not set to false in your config
  • API users see no usage display because they are billed per token, not rate-limited
  • If ANTHROPIC_BASE_URL or ANTHROPIC_API_BASE_URL is set to a non-default value, usage display is skipped because the Anthropic OAuth usage API may not apply
Behind a proxy? Set HTTPS_PROXY (or HTTP_PROXY / ALL_PROXY) and optionally NO_PROXY before launching Claude Code. See the proxy table above. Slow or inconsistent usage data? Increase CLAUDE_HUD_USAGE_TIMEOUT_MS to give the API more time to respond. You can also increase usage.cacheTtlSeconds to reduce how often fresh data is fetched. Using AWS Bedrock? Bedrock models display Bedrock in the plan label and hide usage limits. Usage for Bedrock is managed in your AWS account.

Build docs developers (and LLMs) love

Get started for freeTalk to us