opencode-headroomContext compression plugin for opencode — port of headroom with Kneedle adaptive-K, BM25 relevance scoring, and CCR reversibility
0
56
16 in 7 days
27.3
Multi-signal model
2 months ago
2026-06-11
Install and configure
opencode.jsonWrites to this project's opencode.json — applies to this repository only.
opencode.json
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["opencode-headroom@0.1.0"]
}Writes to ~/.config/opencode/opencode.json — applies to every project.
~/.config/opencode/opencode.json
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["opencode-headroom@0.1.0"]
}If you want to modify the plugin locally, install it into the project and reference the local path.
shell
pnpm add -D opencode-headroomopencode loads npm dependencies through its embedded runtime on startup and caches them locally — no manual global install needed.
Context compression plugin for opencode — port of headroom v0.24.0.
Reduces token usage 60–95% on large tool outputs, logs, diffs, and search results — without losing information the LLM needs. Original content is cached locally (CCR) for on-demand retrieval.
Quick start
npm install @ngotrnghia1811/opencode-headroom
// opencode.json
{
"plugin": ["@ngotrnghia1811/opencode-headroom"]
}
Documentation
| Document | Description |
|---|---|
| SETUP.md | Installation, configuration, troubleshooting |
| DEVELOPMENT-PLAN.md | Full porting plan, architecture, implementation phases |
| discrepancy.md | Documented differences from upstream headroom v0.24.0 |
| headroom-learn-todo.md | Design doc for deferred headroom-learn feature |
Tools provided
headroom_stats— session compression metrics (tokens saved, compressor hits)headroom_retrieve(hash)— retrieve original content from CCR<<ccr:HASH>>markers
Development
bun install
bun test # 178 tests
bun run typecheck # bundle check
License
Apache 2.0