mirror of https://github.com/headroomlabs-ai/headroom.git synced 2026-08-27 14:17:10 -04:00

Rudimar Ronsoni fa05ebc849

docs: clarify OpenCode integration (#1317 )

## Description

Clarifies the OpenCode documentation follow-up for PR #1105 so users can
install `headroom-opencode`, configure provider routing, use the native
plugin, and copy working retrieve/compression helper examples.

## Type of Change

- [x] Documentation update
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change

## Changes Made

- Documented how `headroom wrap opencode` wires provider config, MCP
tools, and runtime environment.
- Documented the native `HeadroomPlugin` path, `HEADROOM_PROXY_URL`,
retrieve tooling, and programmatic config helpers.
- Fixed `plugins/opencode/README.md` examples so `compressWithHeadroom`
uses the exported options-object API and `headroom_retrieve` uses
`hash`.

## Testing

- [x] Type checks pass.
- [x] Unit tests pass.
- [x] Whitespace check passes.

### Test Output

```text
plugins/opencode: npm run typecheck
> tsc --noEmit

plugins/opencode: npm test
Test Files  2 passed (2)
Tests  9 passed (9)

docs: npm run types:check
✓ Types generated successfully

repo: git diff --check
(no output)
```

## Real Behavior Proof

- Environment: Local macOS worktree at
`docs/pr-1105-documentation-followup`, Node/npm project commands run
from `plugins/opencode` and `docs`.
- Exact command / steps: Updated the README snippets, ran `npm run
typecheck`, reran `npm test` with elevated permissions after the sandbox
blocked a local `127.0.0.1` listener, ran `npm run types:check` in
`docs`, and ran `git diff --check`.
- Observed result: Typecheck completed with `tsc --noEmit`; the OpenCode
package test suite reported 2 files and 9 tests passed; docs type
generation completed successfully; `git diff --check` produced no
output.
- Not tested: Browser-rendered documentation preview. `docs: npm run
build` was started locally but produced no output for roughly 90 seconds
and was stopped, so this follow-up does not claim a fresh local docs
build result.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Additional Notes

- The linked review comment asked for README examples to match
`compressWithHeadroom(messages, options)` and
`createHeadroomRetrieveTool` requiring `hash`; both snippets now match
the exported API.

2026-06-24 21:54:05 -05:00

2.8 KiB

Raw Blame History

headroom-opencode

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

Provider config helpers used by headroom wrap opencode and persistent installs.
A native OpenCode plugin that installs Headroom transport interception and exposes the retrieve tool.

Install

npm install headroom-opencode

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

Use HeadroomPlugin when OpenCode should intercept provider traffic in-process and expose Headroom tooling from a plugin.

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",
  });
}

HeadroomPlugin:

installs Headroom transport interception for OpenCode provider traffic.
exposes the headroom_retrieve tool.
publishes HEADROOM_PROXY_URL in the plugin output env.
defaults to http://127.0.0.1:8787 when no proxy URL is supplied.

Retrieve Tool

import { createHeadroomRetrieveTool } from "headroom-opencode";

const retrieve = createHeadroomRetrieveTool({
  proxyBaseUrl: "http://127.0.0.1:8787",
});

const result = await retrieve.execute({
  hash: "0123456789abcdef01234567",
  query: "needle",
});

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`
`OPENCODE_CONFIG_CONTENT`	OpenCode wrapper	Generated OpenCode provider, model, and MCP config

License

Apache-2.0

2.8 KiB Raw Blame History