Plugin Store · Hook · Gate

Headroom

Docs GitHub 7.3K

headroom-hook v2.0.1 · built on headroom v0.33.0

Context compression, on the path.

Every tool call, DB query, file read, and RAG retrieval your agent makes is mostly boilerplate: noise the model pays to read on every request. Trimming it away usually means bespoke work in each app, rebuilt for every provider whose limits differ.

The Headroom project already solves the hard part: it compresses that boilerplate away before it hits the model, so the LLM sees less noise, responds faster, and costs less. The Busbar hook is a thin rewrite gate that runs it on the path: it hands each request to Headroom before it ships, no app changes required.

Because the gate fires on Busbar’s normalized IR, that one integration covers every wire protocol and provider at once, with failover and circuit breaking underneath it. Headroom does the compression; Busbar puts it in front of every model you call.

Measured the way Busbar measures itself, from Busbar’s own clock. Busbar reports its internal processing time (total minus the upstream round-trip) in a Server-Timing: busbar;dur header, and the Headroom gate runs synchronously inside that window, so this is exactly what the hook adds, floor-free. busbar;dur in µs, concurrency 1, 1,000 requests, 11 KB noisy tool-log history:

This isn’t a compression benchmark; how well Headroom compresses is the Headroom project’s craft, and it reports higher ratios than the ~50% seen here (66–94% on some content), with more to gain from tuning. What we checked is that the plumbing is sound: the mock upstream tallies the tokens it actually received, so this really shipped to the provider: an 11 KB noisy tool-log history goes 2,832 → 1,422 input tokens. Short conversational chats abstain and pass through byte-identical (100% abstain over 100 short chats), and if the hook is ever slow, wrong, or down the request proceeds with its original body.

For scale: Headroom’s own HTTP proxy reports a 52 ms median overhead from production telemetry (50,000+ sessions), which (as they rightly note) is negligible against multi-second inference. The same compression core, run as a Busbar gate, measures in the hundreds of microseconds on Busbar’s clock. Both are small next to the model call; we make no claim about how their proxy is deployed. Headroom does the compression; Busbar just puts it in front of every model you call.

docker run -d -p 8080:8080 \
  -e ANTHROPIC_KEY -e BUSBAR_ADMIN_TOKEN \
  getbusbar/busbar-headroom

global_hooks:
  - module: busbar-headroom
    kind: gate
    prompt: rw            # the rewrite grant
    timeout_ms: 25         # ~550 µs typical; 25 ms is generous headroom
    on_error: nothing      # a broken compressor never touches a request
    settings:
      target_ratio: 0.5
      min_savings_pct: 10

← Back to the Plugin Store