# headroom-opencode

Headroom proxy integration for [OpenCode](https://opencode.ai). Routes LLM traffic through the Headroom proxy for token compression, provides CCR retrieval, and handles provider configuration.

## Install

```bash
npm install headroom-opencode
```

## Quick start

### Create a Headroom provider for opencode.json

```ts
import { createHeadroomProvider } from "headroom-opencode";

const provider = createHeadroomProvider({
  proxyPort: 8787,
});

// Write to opencode.json:
// {
//   "provider": { "headroom": provider },
//   "model": "headroom/claude-sonnet-4-6"
// }
```

### Build OPENCODE_CONFIG_CONTENT

```ts
import { buildOpencodeConfigContentJson } from "headroom-opencode";

const json = buildOpencodeConfigContentJson({
  proxyPort: 8787,
  defaultModel: "claude-sonnet-4-6",
});

// Set as env var: process.env.OPENCODE_CONFIG_CONTENT = json;
```

### Compress messages through the proxy

```ts
import { compressWithHeadroom } from "headroom-opencode";

const result = await compressWithHeadroom(messages, {
  model: "gpt-4o",
  proxyUrl: "http://localhost:8787",
});

console.log(`Saved ${result.tokensSaved} tokens`);
```

### CCR retrieve tool

```ts
import { createHeadroomRetrieveTool } from "headroom-opencode";

const retrieveTool = createHeadroomRetrieveTool({
  proxyBaseUrl: "http://localhost:8787",
});

// Register in OpenCode's MCP config under mcp.headroom_retrieve
```

## API

### `createHeadroomProvider(options?)`

Creates a provider object compatible with OpenCode's `@ai-sdk/openai-compatible` format.

| Option | Default | Description |
|---|---|---|
| `proxyBaseUrl` | `http://127.0.0.1:8787` | Full proxy base URL |
| `proxyPort` | `8787` | Proxy port (ignored if proxyBaseUrl is set) |
| `models` | See below | Custom model mappings |
| `defaultModel` | `claude-sonnet-4-6` | Default model ID |

### `buildOpencodeConfigContent(options?)`

Returns a full `OPENCODE_CONFIG_CONTENT` JSON object with provider and model.

### `buildOpencodeConfigContentJson(options?)`

Same as above but returns a JSON string ready for the `OPENCODE_CONFIG_CONTENT` env var.

### `compressWithHeadroom(messages, options?)`

Compresses an array of messages through the Headroom proxy. Returns compression stats and compressed messages.

### `createHeadroomRetrieveTool(config)`

Creates a CCR retrieve tool for OpenCode's MCP system.

### `setDefaultProxyUrl(url)` / `getDefaultProxyUrl()`

Set or get the default proxy URL for all operations. Defaults to `HEADROOM_BASE_URL` env var or `http://localhost:8787`.

## Default models

| Model ID | 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 |

## OpenCode plugin

The package default export is an OpenCode plugin. It adds a `headroom_retrieve`
tool and Headroom metadata for shell commands:

```json
{
  "plugin": [["headroom-opencode", { "proxyUrl": "http://127.0.0.1:8787" }]]
}
```

The plugin does not set `OPENAI_BASE_URL` or `ANTHROPIC_BASE_URL`. Model traffic
is routed by the `headroom` provider config generated by
`buildOpencodeConfigContent` or `headroom wrap opencode`.

## License

Apache-2.0