{"_id":"@ashutoshsinghpr7/opencode-headroom","name":"@ashutoshsinghpr7/opencode-headroom","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"$schema":"https://json.schemastore.org/package.json","name":"@ashutoshsinghpr7/opencode-headroom","version":"1.0.0","type":"module","description":"OpenCode plugin that compresses tool outputs in real-time — strip progress noise, deduplicate lines, truncate large outputs, and track token savings in the TUI","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"clean":"rm -rf dist","build":"npm run clean && tsup && tsc --emitDeclarationOnly","dev":"opencode plugin dev","typecheck":"tsc --noEmit","test":"node --import tsx --test tests/*.test.ts","format":"prettier --write .","format:check":"prettier --check .","prepublishOnly":"npm run build"},"keywords":["opencode","opencode-plugin","plugin","token-savings","context-compression","headroom","tool-output","prompt-optimization"],"repository":{"type":"git","url":"git+https://github.com/ashutoshsinghpr7/opencode-headroom.git"},"bugs":{"url":"https://github.com/ashutoshsinghpr7/opencode-headroom/issues"},"homepage":"https://github.com/ashutoshsinghpr7/opencode-headroom#readme","author":{"name":"ace"},"license":"MIT","peerDependencies":{"@opencode-ai/plugin":">=1.4.3"},"devDependencies":{"@opencode-ai/plugin":"^1.4.3","@types/node":"^25.5.0","prettier":"^3.8.1","tsup":"^8.5.1","tsx":"^4.21.0","typescript":"^6.0.2"},"gitHead":"3dcc027f3d4b2e28519387999b8180762bf561fb","_id":"@ashutoshsinghpr7/opencode-headroom@1.0.0","_nodeVersion":"24.11.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-jfMnj5kHetSRX0d0SfaHQfzaM4uwHDk+xS9vPrsW6zibQAFtuIZmb+/w6ZnV9BPn51n+Ju3hNbli5dk6d2365w==","shasum":"4c4ca67c638681bee694c8e66ac5eacb15c0b2de","tarball":"https://registry.npmjs.org/@ashutoshsinghpr7/opencode-headroom/-/opencode-headroom-1.0.0.tgz","fileCount":10,"unpackedSize":32836,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAoi8Kru1+5HIpV4Te1qMot0C0CD0Kh88mfi70LTOv2NAiEAx9kHBnTFQzCGBTwyTgdUN+pQYrlxSxtqy+4n/nAMQFU="}]},"_npmUser":{"name":"ashutoshsinghpr7","email":"ashutosh.singhpr7@gmail.com"},"directories":{},"maintainers":[{"name":"ashutoshsinghpr7","email":"ashutosh.singhpr7@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/opencode-headroom_1.0.0_1782986583777_0.4715331105780656"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-02T10:03:03.588Z","1.0.0":"2026-07-02T10:03:03.915Z","modified":"2026-07-02T10:03:04.174Z"},"maintainers":[{"name":"ashutoshsinghpr7","email":"ashutosh.singhpr7@gmail.com"}],"description":"OpenCode plugin that compresses tool outputs in real-time — strip progress noise, deduplicate lines, truncate large outputs, and track token savings in the TUI","homepage":"https://github.com/ashutoshsinghpr7/opencode-headroom#readme","keywords":["opencode","opencode-plugin","plugin","token-savings","context-compression","headroom","tool-output","prompt-optimization"],"repository":{"type":"git","url":"git+https://github.com/ashutoshsinghpr7/opencode-headroom.git"},"author":{"name":"ace"},"bugs":{"url":"https://github.com/ashutoshsinghpr7/opencode-headroom/issues"},"license":"MIT","readme":"# opencode-headroom\n\nReal-time tool output compression for [OpenCode](https://opencode.ai) — strip progress noise, deduplicate lines, truncate large outputs, and track token savings directly in the TUI.\n\nInspired by [headroom-desktop](https://github.com/gglucass/headroom-desktop), but works natively inside OpenCode's plugin system — no proxy, no external runtime, zero host pollution.\n\n## How it works\n\nHeadroom hooks into every tool execution (bash, read, grep, glob, webfetch) via OpenCode's plugin hooks and applies three compression strategies **before** the output enters the context window:\n\n| Strategy                    | What it does                                                                | Applied to       |\n| --------------------------- | --------------------------------------------------------------------------- | ---------------- |\n| **Strip progress noise**    | Removes progress bars, spinners, download percentages, build progress lines | bash output      |\n| **Deduplicate lines**       | Collapses repeated lines (e.g. identical grep results) into one             | bash, grep, glob |\n| **Summarize large outputs** | Truncates 100+/500+ line outputs, keeping head + tail + sample              | all tools        |\n\nEverything runs locally in-memory — no external services, no API calls, no data leaves your machine.\n\n## Installation\n\n```bash\nopencode plugin opencode-headroom --global\n```\n\nOr add to your `opencode.json` manually:\n\n```json\n{\n  \"plugin\": [\"opencode-headroom\"]\n}\n```\n\nLocal plugins are also auto-loaded from `.opencode/plugins/` or `~/.config/opencode/plugins/`.\n\n### Dependencies\n\nHeadroom requires these peer dependencies:\n\n- `@opencode-ai/plugin` — core plugin API\n- `@opentui/core` / `@opentui/solid` — for the sidebar TUI panel\n- `solid-js` — for reactive UI rendering\n\nIf you're using the project-local approach, add them to your `.opencode/package.json`:\n\n```json\n{\n  \"dependencies\": {\n    \"@opencode-ai/plugin\": \">=1.4.3\",\n    \"@opentui/core\": \">=0.4.0\",\n    \"@opentui/solid\": \">=0.4.0\",\n    \"solid-js\": \">=1.0.0\",\n    \"opencode-headroom\": \"*\"\n  }\n}\n```\n\n## Features\n\n### Tool output compression\n\n- **bash**: strips progress noise → deduplicates lines → summarizes if >100 lines\n- **read**: summarizes large file reads (>100 lines) keeping head and tail\n- **grep / glob**: deduplicates repeated lines\n- **webfetch**: summarizes fetched content\n\n### TUI integration\n\n- **Sidebar panel**: persistent stats in the right panel showing tokens saved, compressions, timing breakdowns, and performance verdict (reactive, updates every 2s)\n- **Periodic toasts**: every 5 compressions, shows total tokens saved + avg time per compression\n- **Session summary**: when OpenCode goes idle, shows total savings with performance verdict\n- **Manual stats**: type `/headroom-stats` to see live stats at any point\n\n### Configuration\n\nTo enable the sidebar panel, add headroom to your `tui.json`:\n\n```json\n{\n  \"plugin\": [\"opencode-headroom\"]\n}\n```\n\n### Performance tracking\n\nHeadroom measures and reports its own performance impact:\n\n| Verdict        | Total compression time | Impact                        |\n| -------------- | ---------------------- | ----------------------------- |\n| **Negligible** | < 100 ms               | Immeasurable                  |\n| **Minimal**    | < 500 ms               | Barely noticeable             |\n| **Moderate**   | < 2,000 ms             | Might add slight latency      |\n| **Noticeable** | ≥ 2,000 ms             | Consider adjusting thresholds |\n\nIn practice, average compression takes **~138 µs** (microseconds). Even 1,000 compressions only use ~138ms total across the entire session.\n\n## Performance benchmarks\n\nTested on MacBook Pro M1 (Node.js v24.11), 10,000 iterations each:\n\n| Test                   | Input                   | Savings       | Avg Time |\n| ---------------------- | ----------------------- | ------------- | -------- |\n| npm install noise      | 3,775 chars / 250 lines | 627 tokens    | 31.7 µs  |\n| grep with 200 dupes    | 4,422 chars / 202 lines | 1,200 tokens  | 16.5 µs  |\n| Large file (850 lines) | 40,689 chars            | 11,600 tokens | 13.2 µs  |\n| Full bash pipeline     | 11,285 chars            | 3,200 tokens  | 76.9 µs  |\n\n**Verdict: negligible performance impact** — compression runs in microseconds, three orders of magnitude below perceptible LLM response latency (2-5 seconds).\n\n## Configuration\n\nHeadroom works out of the box with sensible defaults. The following constants are available in the source if you need to tune them:\n\n| Setting                       | Default                            | Description                                    |\n| ----------------------------- | ---------------------------------- | ---------------------------------------------- |\n| `COMPRESSION_THRESHOLD`       | 2000                               | Minimum chars in output to trigger compression |\n| `TOAST_INTERVAL_COMPRESSIONS` | 5                                  | Toast every N compressions                     |\n| Compressible tools            | `bash, read, grep, glob, webfetch` | Tools whose outputs get compressed             |\n\n## Comparison with DCP\n\nYou can use Headroom alongside [opencode-dcp](https://github.com/Opencode-DCP/opencode-dynamic-context-pruning) — they work at different levels:\n\n|                        | Headroom                         | DCP                             |\n| ---------------------- | -------------------------------- | ------------------------------- |\n| **What it compresses** | Tool outputs (in real-time)      | Conversation history (messages) |\n| **When**               | Before output enters context     | Periodically / on demand        |\n| **Strategy**           | Strips noise, dedupes, truncates | Generates summaries via LLM     |\n| **Perf impact**        | Microseconds                     | Seconds (LLM call)              |\n\nThey're complementary — Headroom reduces context bloat from noisy tool outputs, DCP handles stale conversation turns.\n\n## Commands\n\n| Command           | What it does                               |\n| ----------------- | ------------------------------------------ |\n| `/headroom-stats` | Shows current session stats as a TUI toast |\n\n## Development\n\n```bash\n# Clone the repo\ngit clone https://github.com/ace/opencode-headroom\ncd opencode-headroom\n\n# Link locally for testing\n# In your project's opencode.json:\n{ \"plugin\": [\"/absolute/path/to/opencode-headroom\"] }\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-4b7c74e45ae84d5d4ba7086b42527081"}