Headroom Compression

What It Does

Headroom is a context-compression service that rewrites bulky tool output and retrieved documents before a request reaches the model. It is generally available on the CBorg API and is enabled by default for all chat models. This default compression is completely non-lossy (lossless) and structural-only, typically achieving ~10% token savings in practice (up to ~50% in theory) by stripping redundant syntax, whitespace, and formatting.

Headroom only compresses tool-role message content (the results of tool calls, retrieved documents, and similar bulky machine-generated output). Your own prose – system prompts, user turns, assistant replies – is never rewritten. This means agentic coding workloads that accumulate large tool results benefit the most. Ordinary conversational chat, which carries little or no tool output, will see little or no change.

Note

Lossless Default: Headroom’s default structural compression is entirely lossless and safe for general use. It only strips structural/formatting overhead and never discards content.

Optional Lossy Compression: An optional, more aggressive, lossy compression profile is available via the -compressed variants (guardrail headroom-compressed, achieving around 50% savings in practice for coding agents, but can be up to 90% if the context is mostly text, using ML-based Kompress compression and tool search/smart crusher). This can alter wording semantically. Only opt into these models or the headroom-compressed guardrail for tasks where exact wording of tool output is not required. If the compression service is unavailable, the request proceeds uncompressed rather than failing.

Compression Profiles

By default, all requests to chat models automatically use the lossless/structural compression profile (headroom-default). If you wish to use the more aggressive ML compression profile, an option is available:

Default: Lossless/Structural Compression (coding profile)

  • Guardrail name: headroom-default
  • Typical savings: ~10% in practice (~50% theoretical best case)
  • ML-based Kompress: Disabled
  • How to use: Applied automatically to all standard chat models and -compact variants (e.g., claude-sonnet-5, claude-sonnet-5-compact), or explicitly via {"guardrails": ["headroom-default"]}.

Opt-in: Aggressive ML-Based Compression (agent-90 profile)

  • Guardrail name: headroom-compressed
  • Typical savings: ~50% in practice for coding agents (up to 90% if context is mostly text)
  • ML-based Kompress: Enabled (lossy semantic compression with retrieval markers and tool search)
  • How to use: Append -compressed to any model name (e.g., claude-sonnet-5-compressed), or pass {"guardrails": ["headroom-compressed"]} in the request body.

Request Body Selection

Add a guardrails field naming headroom-default or headroom-compressed to the request body:

curl https://api.cborg.lbl.gov/chat/completions \
  -H "Authorization: Bearer $CBORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "guardrails": ["headroom-compressed"],
    "messages": [{"role": "user", "content": "Hello"}]
  }'

With the OpenAI Python SDK, pass the same field through extra_body:

import os
import openai

client = openai.OpenAI(
    api_key=os.environ["CBORG_API_KEY"],
    base_url="https://api.cborg.lbl.gov",
)

response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={"guardrails": ["headroom-compressed"]},
)

Disabling Compression

If you need the exact, uncompressed tool output for a specific request or session, you can disable default compression.

Option 1: Request Bypass Header (Per Request)

Send the x-headroom-bypass: true HTTP header with your request:

curl https://api.cborg.lbl.gov/chat/completions \
  -H "Authorization: Bearer $CBORG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-headroom-bypass: true" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Option 2: Environment Variable (For Claude Code & Anthropic SDK)

Claude Code (and other Anthropic-format clients that route through CBorg) supports the ANTHROPIC_CUSTOM_HEADERS environment variable, which adds one or more headers to every request the tool makes. To disable Headroom compression for an entire Claude Code session, set:

export ANTHROPIC_CUSTOM_HEADERS="x-headroom-bypass: true"

Add this alongside the other environment variables described in the Claude Code with CBorg guide before starting claude. Unset the variable, or start a new shell without it, to re-enable compression.

See Also