Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
headroom-opencode
OpenCode integration helpers for Headroom. The package supports two integration paths:
- Provider config helpers used by
headroom wrap opencodeand persistent installs. - A native OpenCode plugin that installs Headroom transport interception and exposes the retrieve tool.
Install
npm install headroom-opencode
Building from source
Tsup 9 requires Node.js ^22.18.0 || ^24.11.0 || >=26.0.0. The current locked
graph also includes ini 7, which requires ^22.22.2 || ^24.15.0 || >=26.0.0.
These are development-install requirements; the published plugin and its host
retain their own runtime requirements. Node.js 24.22.2 is a verified choice
for this dependency graph. From plugins/opencode, run:
npm ci
npm test
npm run typecheck
npm run build
npm run build:standalone
For a reproducible real OpenCode 2.x → proxy → local SSE upstream check, see the transport runtime proof. It records the tested scope and limitations.
Provider Config Helpers
Use these helpers when you need to generate OpenCode config that routes a headroom provider through a running Headroom proxy.
import {
buildOpencodeConfigContent,
createHeadroomProvider,
} from "headroom-opencode";
const provider = createHeadroomProvider({ proxyPort: 8787 });
const config = buildOpencodeConfigContent({
proxyPort: 8787,
defaultModel: "claude-sonnet-4-6",
});
console.log(provider.provider.headroom.npm);
console.log(config.model);
The generated provider uses @ai-sdk/openai-compatible and points model requests at http://127.0.0.1:<port>/v1.
Native OpenCode Plugin
The package's default export is an OpenCode plugin that loads on both OpenCode 1.x and 2.x. Register it in opencode.json:
{
"plugin": [
["headroom-opencode", { "proxyUrl": "http://127.0.0.1:8787" }]
]
}
OpenCode 2.x migrates the 1.x plugin key automatically. To configure it the 2.x way, use "plugins": [{ "package": "headroom-opencode", "options": { ... } }].
The default export is { id: "headroom", server, setup }. OpenCode 1.x calls server (HeadroomPlugin) and 2.x calls setup (headroomSetup); each ignores the other's field. Both entry points:
- install Headroom transport interception for OpenCode provider traffic.
- expose the
headroom_retrievetool (a direct tool on 2.x, not only through code mode). - add
HEADROOM_ACTIVE,HEADROOM_PROXY_URL,HEADROOM_PROJECT(andHEADROOM_BACKENDwhen set) to shell command environments. - default to
HEADROOM_PROXY_URL, thenhttp://127.0.0.1:8787, when noproxyUrloption is supplied. - skip routing for hosts listed in
excludeHosts(orHEADROOM_OPENCODE_EXCLUDE_HOSTS); those requests go straight upstream with no compression or telemetry.
On 2.x, setup returns a cleanup that releases the transport, so hot reloads do not stack interceptors.
OpenCode 2.x keeps its own reference to fetch from before plugins load, so patching fetch alone does not catch its model traffic. For models with a resolved baseURL, the plugin also rewrites OpenAI chat-completions, Responses, and Anthropic Messages traffic so that it points at the proxy — including GitHub Copilot's Claude models. Anthropic Messages base URLs with a path prefix (for example a gateway rooted at /api/...) stay on their own base URL, because the proxy's Messages route ignores the original-path header and cannot preserve that prefix. Headers name the real upstream and request path, as the transport does, and authentication settings are retained. Local, excluded, and unsupported-protocol models are left alone. headroom wrap opencode routes native Anthropic and OpenAI through the proxy separately, via their baseURL.
To keep a provider off the proxy, list its host. An entry matches the host and all of its subdomains, and .example.com / *.example.com are accepted as spellings of example.com:
// opencode.json
{
"plugin": [["/path/to/headroom/providers/opencode/_dist", { "excludeHosts": ["opencode.ai"] }]]
}
or, for headroom wrap opencode and spawned Node child processes, set the environment variable before launching:
HEADROOM_OPENCODE_EXCLUDE_HOSTS="opencode.ai,.corp.internal" headroom wrap opencode
Retrieve Tool
import { createHeadroomRetrieveTool } from "headroom-opencode";
const retrieve = createHeadroomRetrieveTool({
proxyBaseUrl: "http://127.0.0.1:8787",
});
const result = await retrieve.execute({
hash: "0123456789abcdef01234567",
});
The tool calls /v1/retrieve/<hash> on the Headroom proxy.
Compression Helper
import { compressWithHeadroom } from "headroom-opencode";
const result = await compressWithHeadroom(
[{ role: "user", content: "Summarize this file" }],
{ model: "gpt-4o", proxyUrl: "http://127.0.0.1:8787" },
);
console.log(`Saved ${result.tokensSaved} tokens`);
Models
| Model | Context | Output |
|---|---|---|
claude-sonnet-4-6 |
200K | 16K |
claude-opus-4-6 |
200K | 16K |
claude-haiku-4-5-20251001 |
200K | 8K |
gpt-4o |
128K | 16K |
gpt-4.1 |
1M | 32K |
The provider config exposes these as headroom/<model> and defaults to headroom/claude-sonnet-4-6.
Environment
| Variable | Used by | Description |
|---|---|---|
HEADROOM_PROXY_URL |
Native plugin | Proxy URL used by HeadroomPlugin |
HEADROOM_OPENCODE_EXCLUDE_HOSTS |
Native plugin | Comma-separated hosts (and their subdomains) that bypass the proxy; the excludeHosts plugin option takes precedence |
OPENCODE_CONFIG_CONTENT |
OpenCode wrapper | Generated OpenCode provider, model, and MCP config |
License
Apache-2.0