[DOCS] OpenCode integration guide — wrap, MCP, plugin, and manual setup

[chopratejas]

Summary

Write comprehensive documentation for using Headroom with OpenCode, covering all integration paths from simplest to most advanced.

Context

OpenCode integration has unique challenges compared to Claude Code or Codex:

• ANTHROPIC_BASE_URL env var doesn't work reliably (Vercel AI SDK path construction differs)
• Claude OAuth was removed from OpenCode in March 2026 (Anthropic legal action)
• The reliable path is @ai-sdk/openai-compatible provider config
• OpenCode supports MCP servers and NPM plugins for deeper integration

Users need clear guidance on which integration path to use and how to set it up.

Documentation structure

1. Quick start (30 seconds)

pip install headroom-ai[proxy]
headroom wrap opencode

What it does, what to expect, model naming (headroom/claude-sonnet-4-6).

2. Manual setup (without headroom wrap)

For users who want to understand what's happening or customize:

• Start proxy manually: headroom proxy --port 8787
• Add to opencode.json:

  {
    "provider": {
      "headroom": {
        "npm": "@ai-sdk/openai-compatible",
        "options": { "baseURL": "http://127.0.0.1:8787/v1" },
        "models": { ... }
      }
    }
  }

• Explain why ANTHROPIC_BASE_URL doesn't work and why this approach is needed

3. MCP integration

• How to add Headroom MCP tools to OpenCode
• CCR workflow explanation with examples
• Config for both remote (proxy) and local (stdio) MCP modes

4. Plugin installation

• npm install headroom-opencode
• What it provides (auto-proxy, tools, commands)
• Configuration options

5. Troubleshooting

• "Route not found" errors (Vercel AI SDK path issue)
• Model not available (API key permissions)
• Proxy not starting (port conflicts)
• Claude models not working (Anthropic API key required, OAuth removed)

6. FAQ

• "Can I use Claude Max/Pro subscription with OpenCode?" → No, Anthropic blocked OAuth. API keys only.
• "Why do I need to use headroom/model-name instead of anthropic/model-name?" → Routing through proxy requires openai-compatible provider
• "Does this work with OpenCode Zen/Go gateways?" → Yes, but compression is less useful since gateway pricing already includes infrastructure

Location

• docs/integrations/opencode.md in the Headroom repo
• Link from main README under "Integrations" section
• Cookbook example in examples/opencode/

Depends on

• [FEATURE] headroom wrap opencode — CLI wrapper for OpenCode #74 (headroom wrap opencode)
• [FEATURE] OpenCode MCP server integration — headroom_compress, headroom_retrieve, headroom_stats #75 (MCP integration)
• [FEATURE] OpenCode plugin — headroom-opencode npm package #76 (Plugin)

[343242]

Description

Executing the command headroom wrap opencode and the command headroom wrap opencode --port 9999 --no-rtk

To Reproduce

1. Install headroom with pipx install 'headroom-ai[all]'
2. cd my project start to use headroom

Expected Behavior

Successfully started

Actual Behavior

Started error

Error Output

Usage: headroom wrap [OPTIONS] COMMAND [ARGS]...
Try 'headroom wrap --help' for help.
Error: No such command 'opencode'.

Environment

• Headroom version: 0.5.2
• Python version: 3.12.13
• OS: WSL2 with Ubuntu 24.04
• LLM Provider: OpenCode Zen/Go

Additional Context

I read all these issues but didn't find any relevant documents or solutions.

Depends on

• [FEATURE] headroom wrap opencode — CLI wrapper for OpenCode #74 (headroom wrap opencode)
• [FEATURE] OpenCode MCP server integration — headroom_compress, headroom_retrieve, headroom_stats #75 (MCP integration)
• [FEATURE] OpenCode plugin — headroom-opencode npm package #76 (Plugin)

[chopratejas]

Yes, we do not have support for OpenCode today.
This issue was raised so that we can implement its support and then fix the docs for it.

[4fthawaiian]

would be useful to include any instructions for connecting headroom to local llm - it appears to be attempting to pull a model when headroom proxy is started

[rudironsoni]

Update: PR #1105 is already merged. OpenCode can now be 100% wrapped by Headroom with headroom wrap opencode.

[vasilvestre]

Update: PR #1105 is already merged. OpenCode can now be 100% wrapped by Headroom with headroom wrap opencode.

It is mandatory to run headroom wrap opencode each time you start opencode ?