How Claude HUD Implements HTTPS_PROXY Support for the Anthropic Usage API

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.

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

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

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

Authenticated Proxy Access

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

Bypassing the Proxy for Specific Hosts

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, 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 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 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.

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