Skip to content

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.

5.6 KB
Raw Blame

headroom-opencode

OpenCode integration helpers for Headroom. The package supports two integration paths:

  1. Provider config helpers used by headroom wrap opencode and persistent installs.
  2. 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_retrieve tool (a direct tool on 2.x, not only through code mode).
  • add HEADROOM_ACTIVE, HEADROOM_PROXY_URL, HEADROOM_PROJECT (and HEADROOM_BACKEND when set) to shell command environments.
  • default to HEADROOM_PROXY_URL, then http://127.0.0.1:8787, when no proxyUrl option is supplied.
  • skip routing for hosts listed in excludeHosts (or HEADROOM_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