#869·headroom

[FEATURE] Claude Desktop (agent mode) support — Desktop overrides ANTHROPIC_BASE_URL, so init/wrap claude routing never engages

Author: aswin94Created Jun 11, 2026Updated Sep 17, 2026
LabelsLow

Summary

headroom init --global claude works as documented for the terminal Claude Code CLI, but users who primarily run Claude Desktop (macOS com.anthropic.claudefordesktop, agent mode) get no proxy compression at all — Desktop force-sets ANTHROPIC_BASE_URL=https://api.anthropic.com in the spawned session environment, overriding the value Headroom writes to ~/.claude/settings.json.

Environment

  • headroom-ai 0.24.0 (pipx, Python 3.12.5), macOS (Apple Silicon)
  • headroom init --global claude (also re-run with --memory) — settings, hooks, and MCP all installed correctly

What works in Desktop

  • SessionStart hooks fire (the headroom init hook ensure hook runs and keeps the proxy alive)
  • The headroom MCP server loads (headroom_compress / headroom_retrieve / headroom_stats available)

What doesn't

  • Zero /v1/messages ever reach the proxy — only /readyz health polls from the ensure hook. /stats stays at 0 compressed requests.
  • Live session env shows ANTHROPIC_BASE_URL=https://api.anthropic.com despite settings.json env block saying http://127.0.0.1:8787.

Root-cause evidence (from the Desktop app bundle JS)

  • The embedded Anthropic SDK reads baseURL = env(ANTHROPIC_BASE_URL) (standard SDK default — so redirection is mechanically possible).
  • Desktop maintains an allowlist of managed env vars (PATH, CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, …) and replaces them when spawning agent sessions rather than inheriting: a launchctl setenv ANTHROPIC_API_KEY value present in the user launchd env does NOT propagate into the session env, and ANTHROPIC_BASE_URL arrives pre-set to the production endpoint. Presumably this protects subscription OAuth (token scoped to api.anthropic.com).
  • No Desktop config file or UI setting exposes a custom endpoint (checked claude_desktop_config.json, config.json).

Asks

  1. Docs: a note in the agent compatibility matrix / wrap claude docs that Claude Desktop sessions are not covered (only terminal CLI), so users know where the savings do and don't apply.
  2. Feature: a supported Desktop story if feasible — e.g. MCP-first auto-compression guidance for Desktop subscription users (CCR via headroom_retrieve is already a great start), or any sanctioned env-injection path you discover.

Happy to test builds/experiments on a real Desktop setup.

Source: headroomlabs-ai/headroom