headroom [FEATURE] headroom wrap opencode

Summary

Add headroom wrap opencode to launch OpenCode with all API calls routed through the Headroom proxy for context compression.

Background

OpenCode (https://opencode.ai) is an open-source terminal AI coding assistant with 30k+ GitHub stars. It supports 75+ providers via the Vercel AI SDK. Unlike Claude Code or Codex, OpenCode does not reliably support ANTHROPIC_BASE_URL or OPENAI_BASE_URL env vars — the Vercel AI SDK constructs API paths differently, causing "Route not found" errors (opencode#183).

Additionally, Anthropic removed Claude OAuth support from OpenCode in March 2026 following legal action. Claude is only usable via direct API keys.

Approach

The reliable proxy path is the @ai-sdk/openai-compatible provider configured via OPENCODE_CONFIG_CONTENT env var (highest-priority config source, merged with user's existing config).

`headroom wrap opencode` should:

Find the opencode binary (error with install instructions if missing)
Start the Headroom proxy on the configured port (same as other wrap commands)

Inject proxy config via OPENCODE_CONFIG_CONTENT — define a headroom provider:

{
  "provider": {
    "headroom": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Headroom Proxy",
      "options": {
        "baseURL": "http://127.0.0.1:8787/v1"
      },
      "models": {
        "claude-sonnet-4-6": { "name": "Claude Sonnet 4.6", "limit": { "context": 200000, "output": 16384 } },
        "claude-opus-4-6": { "name": "Claude Opus 4.6", "limit": { "context": 200000, "output": 16384 } },
        "claude-haiku-4-5-20251001": { "name": "Claude Haiku 4.5", "limit": { "context": 200000, "output": 8192 } },
        "gpt-4o": { "name": "GPT-4o", "limit": { "context": 128000, "output": 16384 } },
        "gpt-4.1": { "name": "GPT-4.1", "limit": { "context": 1048576, "output": 32768 } }
      }
    }
  },
  "model": "headroom/claude-sonnet-4-6"
}

Set ANTHROPIC_BASE_URL as a fallback (works for some OpenCode versions)
Optionally set up rtk — inject instructions into .opencode/agents/ or project-level instructions file
Launch OpenCode with the modified environment
Clean up on exit (signal handlers, proxy shutdown)

User experience:

# Default — routes through Headroom, uses Claude Sonnet 4.6
headroom wrap opencode

# With a specific model
headroom wrap opencode -- --model headroom/gpt-4o

# Custom port, no rtk
headroom wrap opencode --port 9999 --no-rtk

Model naming convention:

Users reference models as headroom/<model-id> (e.g., headroom/claude-sonnet-4-6). The Headroom proxy maps these to the correct upstream provider automatically. This is explicit and avoids conflicts with the user's existing provider config.

Technical considerations

Config merging: OPENCODE_CONFIG_CONTENT merges with (not replaces) the user's opencode.json. The headroom provider is additive.
Existing model selection: If the user has "model": "anthropic/claude-sonnet-4-5" in their config and we inject "model": "headroom/claude-sonnet-4-6", our config wins (highest priority). This is the desired behavior but should be documented.
API key forwarding: The user's ANTHROPIC_API_KEY / OPENAI_API_KEY env vars are forwarded through the proxy to the upstream provider. No additional auth setup needed.
OpenCode versions: Test against OpenCode 1.3.0+ (post-Anthropic removal). Earlier versions may behave differently.

Acceptance criteria

[ ] headroom wrap opencode starts proxy, injects config, launches OpenCode
[ ] API calls from OpenCode route through Headroom proxy and get compressed
[ ] User can select any headroom/* model
[ ] --no-proxy, --no-rtk, --port, --learn flags work
[ ] Clean shutdown on Ctrl+C
[ ] Documentation in README and headroom wrap --help

Mar 31 '26 01:03 chopratejas

Inject proxy config via OPENCODE_CONFIG_CONTENT — define a headroom provider:

A sidenote, i've seen the best experience with anthropic and openai compatibles itself while using them and changing the baseurl, there are too many model parameters that you might have to just duplicate ( thinking, variants new models etc etc ) and which will be a lot redundant work, recommendation would be to override the baseurl for anthropic and openai endpoint, they can be done, not sure about the env variable but the config has support to override those arguments.

I would consider this a proxy and some plugin support to install hooks etc for some optimal functionality, one reference that you can look at is if it helps you (https://github.com/mksglu/context-mode), this also has nice integration with opencode.

May 05 '26 19:05 manorit2001

is a wrapper around opencode possible? Alternatively, would openceode -> litellm proxy + headroom attachment the next best thing? Tho, if I remember right, headroom bundles litellm under the hood and it was messing with my credential packets.