Headroom

Name: Headroom
Author: ngotrnghia1811

v0.1.6记忆与上下文

@ngotrnghia1811/opencode-headroom

Context compression plugin for opencode — port of headroom with Kneedle adaptive-K, BM25 relevance scoring, and CCR reversibility

维护活跃

#opencode #opencode-plugin #context-compression #token-reduction #llm #headroom

GitHub 仓库 npm 页面官方主页

GitHub 星标

月装机量

近 7 天 8

综合评分SCORE

27.3

生态多维模型

快速安装与配置

opencode.json

写入当前项目的 opencode.json，只对这个仓库生效。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@ngotrnghia1811/opencode-headroom@0.1.6"]
}

写入 ~/.config/opencode/opencode.json，对所有项目生效。

~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@ngotrnghia1811/opencode-headroom@0.1.6"]
}

opencode 启动时会通过内嵌运行时自动加载 npm 依赖并缓存至本地目录，无需手动在全局环境执行安装。

README.md

查看原始文件→

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