Index of every page on this site: llms.txt
All skills
headroomlabs-ai avatar

/headroom

@3a8270b
by Headroom Labsheadroomlabs-ai/headroom80k stars
6,287
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/headroomlabs-ai/headroom/headroom

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈83 tokens for metadata: the name and description. ≈765 when used: this file.

Description uses 4.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈333 characters, or 4.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts16d3 checks · Risk SAFE
  • Gen Agent Trust Hub16d

    The skill provides a utility for compressing large LLM context inputs, such as logs and chat history, to reduce token costs. It involves installing vendor-owned packages and includes instructions for wrapping command-line tools.

  • Socket16d

    No alerts

  • Snyk16d

    Risk: LOW · No issues

Signed by skilld at 3a8270b. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 weeks ago

README badge

README badge for headroomlabs-ai/headroom