Markdown version of https://extraheadroom.com/headroom-opencode

# Headroom for OpenCode: how to set it up

[OpenCode](https://opencode.ai) sends the same kind of bulky context to the model as Claude Code does: file reads, terminal output, and the whole conversation on every turn. Headroom compresses that context locally before it leaves your machine. There are two ways to connect them: the connector in the Headroom desktop app, or `headroom wrap opencode` from the open-source CLI.

## Quick answer

Install the Headroom app, turn on the **OpenCode** connector, and restart OpenCode. Headroom points OpenCode's `anthropic` and `openai` providers at its local proxy in `~/.config/opencode/opencode.json` and registers a small plugin that routes your other providers through it too. Anthropic and OpenAI requests are compressed; other providers pass through uncompressed. The connector is experimental; Claude Code and ChatGPT Codex are Headroom's main connectors. With the CLI instead, run `headroom wrap opencode`.

## Set up with the Headroom app

1. Install OpenCode if you have not yet. Headroom only offers the connector once it detects OpenCode.
2. [Install Headroom](/install-headroom-claude-code) for macOS, Windows, or Linux and open it once.
3. Turn on the **OpenCode** connector in the app.
4. Restart OpenCode so it reads the updated configuration, then run a normal task. Its requests appear in Headroom's activity view.

If OpenCode is missing from the connector list, Headroom did not detect it: install OpenCode and restart Headroom.

## What the connector changes

Everything happens in OpenCode's own config file, with no environment variables or shell profile edits:

- The `baseURL` of the `anthropic` and `openai` providers points at Headroom's proxy on `127.0.0.1:6767`. A base URL you already set yourself is left alone.
- A transport plugin is added to the config's `plugin` list. It routes every other provider through the proxy as well, so their traffic shows up in the activity view, although only Anthropic and OpenAI requests are compressed.
- The file is `~/.config/opencode/opencode.json` (or `opencode.jsonc` if that exists) on macOS and Linux, and `%APPDATA%\opencode\` on Windows.

A project-level `opencode.json` can override these settings for that project. Turning the connector off, quitting Headroom, or [uninstalling it](/docs/uninstall) restores your previous configuration.

## Set up with the open-source CLI

The [Headroom CLI](https://github.com/headroomlabs-ai/headroom) has its own OpenCode integration. With Python 3.10 or newer:

```
pip install "headroom-ai[all]"
headroom wrap opencode
```

`wrap` starts a proxy and points OpenCode at it for that session. You keep the process running yourself and update it with `pip install -U headroom-ai`; the [install guide](/install-headroom-claude-code#open-source-cli) covers the trade-offs. Use one route or the other, not both: the app removes the CLI's provider block when you turn its connector on.

## What to expect

The compression is the same engine that runs for Claude Code and ChatGPT Codex: about 50% fewer tokens on the noisy items it compresses, typically 40-50% across a session, with originals kept on your machine so the model can retrieve them. Sessions heavy on logs, test output, and large file reads gain the most. Because the connector is experimental, a few features that work for Claude Code are not available for OpenCode yet, such as the Serena add-on and the warning Headroom shows when routing breaks.

For background on where the tokens go, see [why Claude Code is so expensive](/why-is-claude-code-expensive); the same patterns apply to OpenCode. [What is Headroom?](/what-is-headroom) covers the rest of the app.