Headroom

Context compression, on the path. Available

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:

	p50	p90	p99
Busbar alone	22 µs	25 µs	30 µs
Busbar + Headroom	569 µs	601 µs	634 µs
Headroom’s added cost	547 µs	576 µs	604 µs

Two things stand out: Busbar itself is tens of µs (the control plane isn’t where your latency goes), and Headroom adds 547 µs with a tight tail (p99 only ~1.1× p50 — both are single Rust binaries, no garbage collector pausing the path). On a two-second inference call that’s 0.03% of the request.

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.

Install it

The hook is a small binary you run alongside Busbar; Busbar connects to it over a Unix socket. You own its lifecycle — Busbar never spawns it; it lazy-connects and reconnects across restarts, so start order doesn’t matter.

Docker (easiest). Two tiny images, one shared socket — copy, paste, running:

curl -fsSL -O https://raw.githubusercontent.com/GetBusbar/headroom-hook/main/docker-compose.yml
curl -fsSL -o config.yaml https://raw.githubusercontent.com/GetBusbar/headroom-hook/main/config.example.yaml
export ANTHROPIC_KEY=sk-ant-...   # or edit config.yaml for your provider
docker compose up

Busbar (:8080) and the compression hook come up together — Headroom is on every request. Edit config.yaml for your own pools. The images are getbusbar/headroom-hook and getbusbar/busbar.

Manual — 1. Get the binary for your platform from the latest release:

Linux x86_64Linux arm64macOS · Apple Silicon

curl -fsSL -o headroom-hook \
  https://github.com/GetBusbar/headroom-hook/releases/latest/download/headroom-hook-linux-x86_64
chmod +x headroom-hook

curl -fsSL -o headroom-hook \
  https://github.com/GetBusbar/headroom-hook/releases/latest/download/headroom-hook-linux-aarch64
chmod +x headroom-hook

curl -fsSL -o headroom-hook \
  https://github.com/GetBusbar/headroom-hook/releases/latest/download/headroom-hook-macos-arm64
chmod +x headroom-hook

Or build from source (needs Rust): git clone https://github.com/GetBusbar/headroom-hook && cd headroom-hook && cargo build --release

2. Run it on a socket:

HEADROOM_SOCKET=/tmp/headroom.sock ./headroom-hook

3. Point Busbar at it, or register it live over the admin API:

hooks:
  headroom:
    kind: gate
    socket: /tmp/headroom.sock
    prompt: rw          # the rewrite grant
    global: true        # attach to every request
    on_error: nothing   # a broken compressor never touches a request

Dashboard. The hook emits Headroom’s own headroom_* Prometheus metrics, and Busbar re-exposes them on /metrics/hooks — so your existing Headroom Grafana dashboard just works, unchanged. Nothing to re-point, nothing to rebuild. A ready-to-import dashboard ships with Headroom itself.

Platforms. The hook speaks a Unix socket, so it runs on Linux and macOS (any arch). There is no native Windows build — run Busbar and the hook together inside WSL2 or a Linux container, where the socket works normally.

See the hooks docs for the full config shape and lifecycle.

Built on open source

Headroom

Every tool call, DB query, file read, and RAG retrieval your agent makes is 70-95% boilerplate. Headroom compresses it away before it hits the model. The LLM sees less noise, responds faster, and costs less.

Project site Source on GitHub Tejas Chopra Discord

Busbar wraps Headroom as a hook so it runs on the request path — all credit for the compression itself goes to its authors. Not affiliated with Busbar.

← Back to the Hook Store