opencode-headroom

Real-time tool output compression for OpenCode — strip progress noise, deduplicate lines, truncate large outputs, and track token savings directly in the TUI.

Inspired by headroom-desktop, but works natively inside OpenCode's plugin system — no proxy, no external runtime, zero host pollution.

How it works

Headroom 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:

| Strategy | What it does | Applied to | | --------------------------- | --------------------------------------------------------------------------- | ---------------- | | Strip progress noise | Removes progress bars, spinners, download percentages, build progress lines | bash output | | Deduplicate lines | Collapses repeated lines (e.g. identical grep results) into one | bash, grep, glob | | Summarize large outputs | Truncates 100+/500+ line outputs, keeping head + tail + sample | all tools |

Everything runs locally in-memory — no external services, no API calls, no data leaves your machine.

Installation

opencode plugin opencode-headroom --global

Or add to your opencode.json manually:

{
  "plugin": ["opencode-headroom"]
}

Local plugins are also auto-loaded from .opencode/plugins/ or ~/.config/opencode/plugins/.

Dependencies

Headroom requires these peer dependencies:

• @opencode-ai/plugin — core plugin API
• @opentui/core / @opentui/solid — for the sidebar TUI panel
• solid-js — for reactive UI rendering

If you're using the project-local approach, add them to your .opencode/package.json:

{
  "dependencies": {
    "@opencode-ai/plugin": ">=1.4.3",
    "@opentui/core": ">=0.4.0",
    "@opentui/solid": ">=0.4.0",
    "solid-js": ">=1.0.0",
    "opencode-headroom": "*"
  }
}

Features

Tool output compression

• bash: strips progress noise → deduplicates lines → summarizes if >100 lines
• read: summarizes large file reads (>100 lines) keeping head and tail
• grep / glob: deduplicates repeated lines
• webfetch: summarizes fetched content

TUI integration

• Sidebar panel: persistent stats in the right panel showing tokens saved, compressions, timing breakdowns, and performance verdict (reactive, updates every 2s)
• Periodic toasts: every 5 compressions, shows total tokens saved + avg time per compression
• Session summary: when OpenCode goes idle, shows total savings with performance verdict
• Manual stats: type /headroom-stats to see live stats at any point

Configuration

To enable the sidebar panel, add headroom to your tui.json:

{
  "plugin": ["opencode-headroom"]
}

Performance tracking

Headroom measures and reports its own performance impact:

| Verdict | Total compression time | Impact | | -------------- | ---------------------- | ----------------------------- | | Negligible | < 100 ms | Immeasurable | | Minimal | < 500 ms | Barely noticeable | | Moderate | < 2,000 ms | Might add slight latency | | Noticeable | ≥ 2,000 ms | Consider adjusting thresholds |

In practice, average compression takes ~138 µs (microseconds). Even 1,000 compressions only use ~138ms total across the entire session.

Performance benchmarks

Tested on MacBook Pro M1 (Node.js v24.11), 10,000 iterations each:

| Test | Input | Savings | Avg Time | | ---------------------- | ----------------------- | ------------- | -------- | | npm install noise | 3,775 chars / 250 lines | 627 tokens | 31.7 µs | | grep with 200 dupes | 4,422 chars / 202 lines | 1,200 tokens | 16.5 µs | | Large file (850 lines) | 40,689 chars | 11,600 tokens | 13.2 µs | | Full bash pipeline | 11,285 chars | 3,200 tokens | 76.9 µs |

Verdict: negligible performance impact — compression runs in microseconds, three orders of magnitude below perceptible LLM response latency (2-5 seconds).

Configuration

Headroom works out of the box with sensible defaults. The following constants are available in the source if you need to tune them:

| Setting | Default | Description | | ----------------------------- | ---------------------------------- | ---------------------------------------------- | | COMPRESSION_THRESHOLD | 2000 | Minimum chars in output to trigger compression | | TOAST_INTERVAL_COMPRESSIONS | 5 | Toast every N compressions | | Compressible tools | bash, read, grep, glob, webfetch | Tools whose outputs get compressed |

Comparison with DCP

You can use Headroom alongside opencode-dcp — they work at different levels:

| | Headroom | DCP | | ---------------------- | -------------------------------- | ------------------------------- | | What it compresses | Tool outputs (in real-time) | Conversation history (messages) | | When | Before output enters context | Periodically / on demand | | Strategy | Strips noise, dedupes, truncates | Generates summaries via LLM | | Perf impact | Microseconds | Seconds (LLM call) |

They're complementary — Headroom reduces context bloat from noisy tool outputs, DCP handles stale conversation turns.

Commands

| Command | What it does | | ----------------- | ------------------------------------------ | | /headroom-stats | Shows current session stats as a TUI toast |

Development

# Clone the repo
git clone https://github.com/ace/opencode-headroom
cd opencode-headroom

# Link locally for testing
# In your project's opencode.json:
{ "plugin": ["/absolute/path/to/opencode-headroom"] }

License

MIT