OpenCode Integration

Use headroom wrap opencode to route OpenCode LLM traffic through the Headroom proxy with a single command. The wrapper starts or reuses the proxy, writes OpenCode config, injects Headroom MCP tools, and launches OpenCode with the generated config.

The headroom-opencode npm package also exports a native OpenCode plugin. The plugin can be used directly from OpenCode config when you want in-process transport interception plus the Headroom retrieve tool.

Quick Start

headroom wrap opencode

When you are done:

headroom unwrap opencode

What wrap opencode Does

Options

headroom wrap opencode \
  --port 8787 \
  --no-mcp \
  --no-serena \
  --code-graph \
  --no-proxy \
  --learn \
  --memory \
  --backend anthropic \
  --anyllm-provider ... \
  --region ... \
  -- <opencode args>

Provider Model Mapping

The generated headroom provider exposes these models through the proxy:

The default model is headroom/claude-sonnet-4-6. Change it in opencode.json or in the generated OPENCODE_CONFIG_CONTENT payload.

Environment Variables

Failure Learning

headroom learn supports OpenCode as a scan target. It reads past sessions from the newer of ~/.local/share/opencode/opencode-local.db and ~/.local/share/opencode/opencode.db, or from HEADROOM_OPENCODE_DB when you set an explicit override, and writes corrections to your project's AGENTS.md.

headroom learn --agent opencode --apply

See Failure Learning for details on the learn system.

Persistent Installs

headroom install supports OpenCode as a target for persistent provider wiring. Use provider scope when you want Headroom to edit opencode.json directly:

headroom install apply --preset persistent-service --scope provider --providers manual --target opencode

This writes the Headroom provider into ~/.config/opencode/opencode.json and keeps the proxy running on port 8787.

The default user scope only writes shell environment configuration. For OpenCode, direct provider config requires --scope provider.

Native OpenCode Plugin

The headroom-opencode package exports HeadroomPlugin for direct OpenCode plugin registration. The plugin installs Headroom transport interception inside OpenCode, exposes the headroom_retrieve tool, and publishes Headroom metadata through the OpenCode plugin output env.

Example:

import { HeadroomPlugin } from "headroom-opencode";

export default async function plugin(input) {
  return HeadroomPlugin(input, {
    proxyUrl: process.env.HEADROOM_PROXY_URL ?? "http://127.0.0.1:8787",
  });
}

Use this plugin when OpenCode should intercept provider traffic in-process. Use headroom wrap opencode when you want the CLI to manage the proxy, config injection, MCP registration, backups, and unwrap behavior.

Programmatic Config Helpers

The package also exports helpers for custom integrations:

import {
  buildOpencodeConfigContent,
  createHeadroomProvider,
  createHeadroomRetrieveTool,
} from "headroom-opencode";

const provider = createHeadroomProvider({ proxyPort: 8787 });
const config = buildOpencodeConfigContent({
  proxyPort: 8787,
  defaultModel: "claude-sonnet-4-6",
});
const retrieve = createHeadroomRetrieveTool({
  proxyBaseUrl: "http://127.0.0.1:8787",
});

How It Works Under The Hood

1. Config injection. The wrapper writes a provider.headroom block into opencode.json. The provider uses @ai-sdk/openai-compatible, which OpenCode supports natively. Model mappings route requests through http://127.0.0.1:<port>/v1.
2. Runtime config. OPENCODE_CONFIG_CONTENT is set as an env var containing provider, plugin, and optional local MCP JSON. OpenCode reads it at startup and merges it with on-disk config.
3. MCP tools. Headroom registers headroom_compress, headroom_retrieve, and headroom_stats through headroom mcp serve unless --no-mcp is set.
4. Native plugin path. HeadroomPlugin installs Headroom transport interception and uses HEADROOM_PROXY_URL or http://127.0.0.1:8787 to reach the proxy.
5. Unwrap. headroom unwrap opencode restores opencode.json from the pre-wrap backup when present, strips Headroom marker blocks when no backup exists, and unregisters Headroom MCP servers.

Troubleshooting

OpenCode does not use the headroom provider.

Check that OPENCODE_CONFIG_CONTENT is set and contains the provider.headroom block. The wrap command prints the env vars it sets.

The native plugin cannot reach Headroom.

Set HEADROOM_PROXY_URL to the running proxy URL, for example http://127.0.0.1:8787.

Provider not found after unwrap.

If unwrap left the provider configured, run headroom unwrap opencode again, or manually restore from ~/.config/opencode/opencode.json.headroom-backup.

Proxy port conflict.

Use --port to select a specific port, or let the proxy auto-select an available one.