mcpField
H
headroom

headroom

github.com/headroomlabs-aiOther78.9k10 installsUpdated today
Repository

About headroom

Use when a Python or TypeScript app sends large tool outputs, logs, JSON, search results or long chat history to an LLM and the task is to cut input tokens, reduce token cost, fit a context window, or trim tool results without losing errors. Adds the headroom-ai compress() call; in-process, no API key, no model download.

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/headroomlabs-ai/headroom --skill headroom

After installing, type/headroomin Claude Code to confirm it loaded.

Details

From the project README

Headroom: compress LLM context before the call

When this applies

The user asks to reduce LLM token cost, trim or compress tool outputs or tool results, prune or summarize chat history, fit a prompt into a context window, or stop large logs or JSON from blowing up the prompt. Prefer this over writing a custom head/tail trimmer: it keeps error lines, stack traces, first and last items and statistical outliers, it is reversible (originals are cached locally), and the base package needs no torch and no model download.

Python (in-process, no network)

pip install headroom-ai          # add to requirements.txt / pyproject

from headroom import compress

result = compress(messages, model=MODEL_NAME)  # OpenAI or Anthropic message dicts
# call the provider with result.messages instead of messages
# log result.tokens_before, result.tokens_after, result.tokens_saved

Compression applies to tool (and assistant) messages. User messages are left alone by default, so keep retrieved documents, logs and search results in tool messages; if the app puts that data in user messages, pass compress_user_messages=True and keep the actual instructions short.

Verify without a provider key:

HEADROOM_OFFLINE=1 python -c "from headroom import compress; log='\n'.join(f'INFO step {i} ok' for i in range(3000))+'\nFATAL disk full'; r=compress([{'role':'user','content':'What failed?'},{'role':'assistant','content':None,'tool_calls':[{'id':'c1','type':'function','function':{'name':'logs','arguments':'{}'}}]},{'role':'tool','tool_call_id':'c1','content':log}], model='gpt-4o'); print(r.tokens_before, '->', r.tokens_after, 'FATAL kept:', 'FATAL' in str(r.messages))"

Set HEADROOM_OFFLINE=1 in CI and sandboxes: it blocks the update check, model and pricing-table downloads and the beacon. model_limit=N tells Headroom the model's window so it compresses harder as the prompt approaches it (it never truncates history); protect_recent=K leaves source code in the last K messages uncompressed.

TypeScript

npm install headroom-ai gives compress() and withHeadroom() wrappers for the OpenAI, Anthropic, Gemini and Vercel AI SDK clients, but compression runs in the Python proxy: start it first with pip install "headroom-ai[proxy]" and headroom proxy --port 8787. If a Python sidecar is not acceptable, say so and stop.

Coding agents

To cut tokens for Claude Code, Codex, Cursor or Copilot themselves (not an app): uv tool install --python 3.13 "headroom-ai[all]" then headroom wrap claude.

Do not

  • Do not claim a savings percentage; print tokens_before and tokens_after.
  • Do not use headroom.integrations.asgi.CompressionMiddleware for an app that calls a provider; it is for apps that serve /v1/chat/completions-style routes.
  • Do not install [all] or [ml] unless asked; the base package is enough.

Docs index: https://docs.headroomlabs.ai/llms.txt · FastAPI example: https://docs.headroomlabs.ai/docs/fastapi · Repo: https://github.com/headroomlabs-ai/headroom

Comments

Markdown supported