# How Claude HUD Implements HTTPS_PROXY Support for the Anthropic Usage API

> Learn how Claude HUD implements HTTPS_PROXY support using a custom Node.js HTTPS agent to route Anthropic API requests through an HTTP CONNECT tunnel. Get detailed insights from the source code.

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

---

**Claude HUD reads standard proxy environment variables and routes API requests through an HTTP CONNECT tunnel using a custom Node.js HTTPS agent defined in [`src/usage-api.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/usage-api.ts).**

The open-source `jarrodwatts/claude-hud` repository isolates all proxy handling within its usage API module. This implementation respects conventional environment variables like `HTTPS_PROXY` while creating secure tunnels specifically for HTTPS traffic to Anthropic's usage endpoint at `api.anthropic.com`.

## Proxy Detection and Environment Variable Parsing

Claude HUD follows industry standards for proxy configuration, checking multiple environment variables before establishing any connection.

### Parsing Standard Proxy Variables

The `getProxyUrl()` function (lines 69‑94 in [`src/usage-api.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/usage-api.ts)) evaluates proxy settings in a specific priority order. It first checks `NO_PROXY`/`no_proxy` to determine if the target host should bypass the proxy entirely. If no bypass rule matches, the function parses any of the following variables into a valid `URL` object:

- `HTTPS_PROXY` or `https_proxy`
- `ALL_PROXY` or `all_proxy`  
- `HTTP_PROXY` or `http_proxy`

Invalid URLs or unsupported protocols are silently ignored, ensuring the application degrades gracefully when environment variables contain malformed data.

### NO_PROXY Bypass Logic

The `isNoProxy()` function (lines 54‑66) implements hostname matching rules to determine when proxying should be skipped. If the target hostname appears in the comma-separated `NO_PROXY` list, Claude HUD connects directly to the Anthropic API without tunneling through the proxy server.

## HTTP CONNECT Tunnel Implementation

When proxy configuration is detected, Claude HUD establishes a tunnel rather than simply forwarding requests. This approach allows end-to-end TLS encryption between the client and Anthropic's API, even when traversing an HTTP proxy.

### Creating the Custom Tunnel Agent

The `createProxyTunnelAgent()` function constructs a specialized `https.Agent` with a custom `createConnection()` method. This implementation performs the following sequence:

1. Opens a raw TCP (or TLS) socket to the proxy server
2. Transmits an HTTP `CONNECT` request: `CONNECT api.anthropic.com:443 HTTP/1.1`
3. Includes a `Proxy-Authorization` header when the proxy URL contains embedded credentials (e.g., `http://user:password@proxy.example.com:3128`)
4. Validates the proxy returns `200 OK`
5. Upgrades the socket to TLS for the final HTTPS connection to the target host

This tunneling approach ensures that sensitive API tokens and usage data remain encrypted between Claude HUD and Anthropic's servers, with the proxy server only seeing encrypted TLS traffic.

### Handling Proxy Authentication

Credential extraction occurs during the `URL` parsing phase. When `user` and `password` components exist in the proxy URL, the agent automatically Base64-encodes them into a `Proxy-Authorization: Basic` header within the `CONNECT` request. This eliminates the need for separate configuration files while maintaining compatibility with enterprise authentication requirements.

## Integrating Proxies into API Requests

The `fetchUsageApi()` function (lines 83‑100) wires the proxy infrastructure into actual HTTP requests. Before initiating the HTTPS request to `api.anthropic.com/v1/usage`, the code executes:

```typescript
const proxyUrl = getProxyUrl('api.anthropic.com');
const options = {
  hostname: 'api.anthropic.com',
  path: '/api/oauth/usage',
  method: 'GET',
  headers: { /* auth headers */ },
  agent: proxyUrl ? createProxyTunnelAgent(proxyUrl) : undefined,
};

```

If `proxyUrl` is defined, the custom agent handles the tunneling transparently. If undefined (either no proxy configured or host matched `NO_PROXY`), the request uses Node.js's default connection behavior.

## Configuration Examples

Configure Claude HUD to route usage API requests through your corporate proxy by setting environment variables before execution:

### Basic HTTPS Proxy Configuration

```bash
export HTTPS_PROXY="http://proxy.example.com:3128"
node dist/index.js < sample-input.json

```

### Authenticated Proxy Access

```bash
export HTTPS_PROXY="http://username:password@proxy.example.com:3128"
node dist/index.js

```

### Bypassing the Proxy for Specific Hosts

```bash
export HTTPS_PROXY="http://proxy.example.com:3128"
export NO_PROXY="api.anthropic.com,localhost,127.0.0.1"
node dist/index.js

```

## Summary

- **Standard Compliance**: Claude HUD recognizes `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY`, and `NO_PROXY` environment variables according to Unix conventions.
- **Isolated Implementation**: All proxy logic resides in [`src/usage-api.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/usage-api.ts), ensuring that HUD rendering and local processing remain unaffected by network configuration.
- **Secure Tunneling**: The `createProxyTunnelAgent` function implements HTTP CONNECT tunneling to maintain end-to-end TLS encryption through intermediary proxies.
- **Authentication Support**: Embedded credentials in proxy URLs are automatically converted to `Proxy-Authorization` headers.

## Frequently Asked Questions

### Which environment variables does Claude HUD check for proxy configuration?

Claude HUD checks `HTTPS_PROXY`, `https_proxy`, `ALL_PROXY`, `all_proxy`, `HTTP_PROXY`, and `http_proxy` in that priority order. For bypass rules, it evaluates `NO_PROXY` and `no_proxy`. These variables are parsed in [`src/usage-api.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/usage-api.ts) by the `getProxyUrl()` and `isNoProxy()` functions.

### How does Claude HUD handle proxy authentication?

When the proxy URL includes credentials (e.g., `http://user:pass@host:port`), the `createProxyTunnelAgent()` function automatically extracts these values and Base64-encodes them into a `Proxy-Authorization: Basic` header sent during the HTTP CONNECT handshake. No additional configuration files are required.

### Can I bypass the proxy for the Anthropic API specifically?

Yes. Set the `NO_PROXY` environment variable to include `api.anthropic.com`. The `isNoProxy()` function performs hostname matching against this list, causing `fetchUsageApi()` to skip proxy initialization and connect directly to Anthropic's servers.

### Does this proxy support apply to all Claude HUD features?

No. The proxy implementation in [`src/usage-api.ts`](https://github.com/jarrodwatts/claude-hud/blob/main/src/usage-api.ts) specifically handles requests to the Anthropic usage API endpoint. Other HUD functionality, including local terminal rendering and input processing, operates independently of these network settings and does not route through the configured proxy.