---
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, adds RTK context filtering, 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 config | Writes a `headroom` provider using `@ai-sdk/openai-compatible` into `opencode.json` and `OPENCODE_CONFIG_CONTENT`, pointing at `http://127.0.0.1:<port>/v1` |
| Runtime env | Sets `OPENCODE_CONFIG_CONTENT` so OpenCode reads provider, model, plugin, and local MCP config at launch |
| Provider compatibility | Leaves `OPENAI_BASE_URL` and `ANTHROPIC_BASE_URL` untouched so OpenCode `/connect` providers keep their own routing |
| Context tool | Injects RTK or `lean-ctx` instructions into `~/.config/opencode/AGENTS.md` and project `AGENTS.md` |
| MCP setup | Registers Headroom MCP tools through a local stdio server: `headroom_compress`, `headroom_retrieve`, and `headroom_stats` |
| Serena MCP | Optionally registers Serena code graph tools. Use `--no-serena` to skip it |
| Backup | Snapshots `opencode.json` to `opencode.json.headroom-backup` before changing it |
| Launch | Starts the `opencode` binary with the generated config |

## Options

```bash
headroom wrap opencode \
  --port 8787 \            # Proxy port. Defaults to a random available port
  --no-rtk \               # Skip RTK context tool injection
  --no-mcp \               # Skip Headroom MCP registration
  --no-serena \            # Skip Serena code graph MCP
  --code-graph \           # Include code graph in context
  --no-proxy \             # Use an existing proxy instead of starting one
  --learn \                # Enable memory and live learning
  --memory \               # Enable persistent memory
  --backend anthropic \    # Backend: anthropic, openai, anyllm
  --anyllm-provider ... \  # AnyLLM provider selection
  --region ... \           # Provider region
  -- <opencode args>       # Arguments passed to the opencode binary
```

## 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, model, plugin, and optional local MCP config injected by `wrap` |
| `HEADROOM_PROXY_URL` | Proxy URL passed to the native `headroom-opencode` plugin. Defaults to `http://127.0.0.1:8787` inside the plugin |
| `HEADROOM_CONTEXT_TOOL` | Set to `lean-ctx` to use lean-ctx instead of RTK |

## Failure Learning

`headroom learn` supports OpenCode as a scan target. It reads past sessions from `~/.local/share/opencode/opencode.db` 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:

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

Provider-only installs do not write Headroom MCP config. MCP tools are added by `headroom wrap opencode` unless `--no-mcp` is set.

## 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, local 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 the full provider, model, plugin, and 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 a local stdio MCP server 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.
