How Custom API Endpoints (`ANTHROPIC_BASE_URL`) Disable Claude HUD’s Usage Display

Setting the ANTHROPIC_BASE_URL or ANTHROPIC_API_BASE_URL environment variable causes Claude HUD to bypass OAuth usage data fetching, completely removing the usage percentage line from the terminal interface.

Claude HUD, an open-source terminal wrapper for Anthropic’s Claude models maintained by jarrodwatts/claude-hud, renders real-time usage statistics by querying Anthropic’s official OAuth endpoint. When you configure a custom API base URL, the HUD assumes you are connecting to a third-party provider and suppresses the usage display because the proprietary usage data is unavailable.

The Detection Logic in src/usage-api.ts

The HUD determines whether to fetch usage data by evaluating your API configuration before making any network requests.

isUsingCustomApiEndpoint() Implementation

In src/usage-api.ts, the function isUsingCustomApiEndpoint() inspects the environment for ANTHROPIC_BASE_URL or the legacy ANTHROPIC_API_BASE_URL. It parses these values and compares their origin against the official endpoint https://api.anthropic.com【source: usage-api.ts lines 60-71】.

If the origins differ, the main getUsage() function aborts immediately, logs “Skipping usage API: custom API endpoint configured”, and returns null instead of a UsageData object. This early return prevents the HUD from attempting to reach https://api.anthropic.com/api/oauth/usage, which would fail or return irrelevant data for non-Anthropic providers.

Why the Usage Line Disappears

The rendering pipeline relies on the object returned by getUsage() to build the terminal output.

The Rendering Pipeline

The usage line renderer located at src/render/lines/usage.ts begins with a strict validation check:

if (!ctx.usageData?.planName) return null;

When getUsage() returns null due to a custom endpoint configuration, ctx.usageData is undefined, causing the renderer to exit silently【source: usage.ts lines 14-16】. Consequently, the HUD skips the usage segment entirely and only displays model selection and context window information.

Visual Comparison

The difference in output is immediate and distinct depending on your environment configuration.

Default Anthropic API (usage line visible):

# No custom base URL configured

export CLAUDE_HUD_USAGE_TIMEOUT_MS=15000
node dist/index.js

# Output:

# Opus | Max │ Context ████░░░░ 45% │ Usage ██░░░░░░░ 27% (1h 30m / 5h)

Custom Endpoint Set (usage line omitted):

# Using a self-hosted or third-party Anthropic-compatible API

export ANTHROPIC_BASE_URL="https://my-private-anthropic.example.com"
node dist/index.js

# Output:

# Opus | Max │ Context ████░░░░ 45%

# (Note: No "Usage" segment appears)

Configuration Scenarios

Your HUD experience depends entirely on whether the environment variables point to the official Anthropic origin:

• Default Configuration: When ANTHROPIC_BASE_URL is unset, the HUD authenticates via OAuth and renders the full usage bar, including percentage consumed, reset timers, and rate-limit warnings.
• Custom Provider: Defining ANTHROPIC_BASE_URL or ANTHROPIC_API_BASE_URL with any value other than the official Anthropic origin triggers API-only mode, hiding usage metrics because the OAuth usage endpoint is not applicable to custom providers.

To restore the usage line while testing against a custom endpoint, you must either unset these variables or modify src/usage-api.ts to remove the early return in isUsingCustomApiEndpoint().

Summary

• Claude HUD fetches usage data exclusively from Anthropic’s OAuth endpoint at https://api.anthropic.com/api/oauth/usage.
• src/usage-api.ts detects custom providers by checking ANTHROPIC_BASE_URL and ANTHROPIC_API_BASE_URL against the official API origin.
• When a custom endpoint is detected, getUsage() returns null, causing src/render/lines/usage.ts to skip rendering the usage line entirely.
• The HUD behaves as an API-only client when these environment variables are configured, displaying model and context information but omitting all usage statistics.

Frequently Asked Questions

Does setting ANTHROPIC_BASE_URL completely disable all HUD features?

No. Only the usage line is suppressed. The HUD continues to display model selection, context window utilization, and other operational metrics. The suppression specifically targets the OAuth-based usage fetch, which is incompatible with third-party endpoints.

Can I restore the usage line while using a custom endpoint?

Not without modifying the source code. You would need to bypass the isUsingCustomApiEndpoint() check in src/usage-api.ts or implement a custom usage provider that returns a compatible UsageData object to the renderer in src/render/lines/usage.ts.

What is the difference between ANTHROPIC_BASE_URL and ANTHROPIC_API_BASE_URL?

ANTHROPIC_BASE_URL is the current standard environment variable, while ANTHROPIC_API_BASE_URL is the legacy alias. The HUD checks both variables in src/usage-api.ts to maintain backward compatibility, treating either one as an indicator of a custom provider configuration.

Where does Claude HUD fetch usage data from by default?

By default, the HUD queries https://api.anthropic.com/api/oauth/usage using OAuth credentials obtained during Claude authentication. This endpoint returns plan details, quota consumption, and reset timestamps, which the HUD renders as the "Usage" segment in the terminal interface.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}