headroom/docs/content/docs/opencode.mdx

---
title: OpenCode Integration
description: Route OpenCode traffic through Headroom for token compression, MCP tools, and cached model access. One command to wrap, one to unwrap.
---

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

```bash
headroom wrap opencode
```

When you are done:

```bash
headroom unwrap opencode
```

## What `wrap opencode` Does

| Step | What happens |
|---|---|
| Proxy | Starts the Headroom proxy unless `--no-proxy` is set |
| Provider injection | Writes a `headroom` provider using `@ai-sdk/openai-compatible` into `opencode.json`, pointing at `http://127.0.0.1:<port>/v1` |
| Runtime env | Sets `OPENCODE_CONFIG_CONTENT` with provider, plugin, and optional local MCP config so OpenCode picks up Headroom at launch |
| Provider compatibility | Leaves `OPENAI_BASE_URL` and `ANTHROPIC_BASE_URL` untouched so OpenCode `/connect` providers keep their own routing |
| MCP setup | Registers the Headroom MCP server (`headroom_compress`, `headroom_retrieve`, `headroom_stats`) |
| Serena MCP | Optionally registers Serena code graph tools (`--no-serena` to skip) |
| Backup | Snapshots `opencode.json` to `opencode.json.headroom-backup` before making any changes |
| Launch | Starts the `opencode` binary through the proxy |

## Options

```bash
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:

| Provider model | Upstream model |
|---|---|
| `headroom/claude-sonnet-4-6` | Claude Sonnet 4.6, 200K context, 16K output |
| `headroom/claude-opus-4-6` | Claude Opus 4.6, 200K context, 16K output |
| `headroom/claude-haiku-4-5-20251001` | Claude Haiku 4.5, 200K context, 8K output |
| `headroom/gpt-4o` | GPT-4o, 128K context, 16K output |
| `headroom/gpt-4.1` | GPT-4.1, 1M context, 32K output |

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

## Environment Variables

| Variable | Description |
|---|---|
| `OPENCODE_CONFIG_CONTENT` | JSON payload with provider, plugin, and optional local MCP config injected by `wrap` |
| `HEADROOM_PROXY_URL` | Proxy URL passed to Headroom MCP when a non-default port is used, and to the native plugin when configured |

## 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`.

```bash
headroom learn --agent opencode --apply
```

See [Failure Learning](/docs/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:

```bash
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:

```ts
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:

```ts
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.