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

> Learn how custom API endpoints like ANTHROPIC_BASE_URL disable Claude HUD's usage display by bypassing OAuth data fetching, removing the usage percentage from your terminal.

- Repository: [Jarrod Watts/claude-hud](https://github.com/jarrodwatts/claude-hud)
- Tags: how-to-guide
- Published: 2026-03-18

---

**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`](https://github.com/jarrodwatts/claude-hud/blob/main/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`](https://github.com/jarrodwatts/claude-hud/blob/main/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`](https://github.com/jarrodwatts/claude-hud/blob/main/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`](https://github.com/jarrodwatts/claude-hud/blob/main/src/render/lines/usage.ts) begins with a strict validation check:

```typescript
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`](https://github.com/jarrodwatts/claude-hud/blob/main/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):**

```bash

# 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):**

```bash

# 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`](https://github.com/jarrodwatts/claude-hud/blob/main/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`](https://github.com/jarrodwatts/claude-hud/blob/main/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`](https://github.com/jarrodwatts/claude-hud/blob/main/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`](https://github.com/jarrodwatts/claude-hud/blob/main/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`](https://github.com/jarrodwatts/claude-hud/blob/main/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`](https://github.com/jarrodwatts/claude-hud/blob/main/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.