[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 ensurehook runs and keeps the proxy alive) - The
headroomMCP server loads (headroom_compress/headroom_retrieve/headroom_statsavailable)
What doesn't
- Zero
/v1/messagesever reach the proxy — only/readyzhealth polls from the ensure hook./statsstays at 0 compressed requests. - Live session env shows
ANTHROPIC_BASE_URL=https://api.anthropic.comdespitesettings.jsonenv block sayinghttp://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: alaunchctl setenv ANTHROPIC_API_KEYvalue present in the user launchd env does NOT propagate into the session env, andANTHROPIC_BASE_URLarrives 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
- Docs: a note in the agent compatibility matrix /
wrap claudedocs that Claude Desktop sessions are not covered (only terminal CLI), so users know where the savings do and don't apply. - Feature: a supported Desktop story if feasible — e.g. MCP-first auto-compression guidance for Desktop subscription users (CCR via
headroom_retrieveis 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