Headroom
Compress LLM context and tool outputs to reduce token costs and fit context windows.
Installation
- Make sure Claude is on your device and in your terminal.
Skills load from
~/.claude/skills/when Claude Code starts up — so you need it on your machine first. If you don't have it yet, install it once with the command below, then runclaudein any terminal to verify.One-time setupnpm i -g @anthropic-ai/claude-codeAlready have it? Skip ahead.
- Paste into Claude Code or into your terminal.
This copies the whole skill folder into
~/.claude/skills/headroom-headroomlabs-ai/— the SKILL.md plus any scripts, reference docs, or templates the skill ships with. Works for every skill.What this command does
- Makes a new, empty temporary folder.
- Downloads the skill's folder,
plugins/headroom-skill/skills/headroom, fromgithub.com/headroomlabs-ai/headroom(branchmain), the GitHub repository it's listed from. You get the version that is there now, not a copy we keep. - Copies that folder to
~/.claude/skills/headroom-headroomlabs-ai/. - Deletes the temporary folder.
Installing runs none of the skill's files; it only downloads and copies them. When you later use the skill, Claude follows its SKILL.md and may run scripts that come with it. Read them first.
Faster alternative (instruction-only skills)
Skips the clone and grabs only the SKILL.md file. Don't use this if the skill ships Python scripts, reference markdowns, or asset templates — they won't be downloaded and the skill will fail when it tries to load them.
Quick install (SKILL.md only)Sign up to copy - Restart Claude Code.
Quit and reopen Claude Code (or any other agent that loads from
~/.claude/skills/). New skills are picked up on startup. - Just ask Claude.
Skills auto-activate when your request matches the skill's description — no slash command needed. Trigger phrases live in the skill's own frontmatter; you can read them in the “What this skill does” section above.
Prefer to read the source first? Open on GitHub.
When Claude uses it
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.
What this skill does
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_beforeandtokens_after. - Do not use
headroom.integrations.asgi.CompressionMiddlewarefor 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
Related skills
Generative Code Art
anthropics
Create algorithmic art with p5.js using randomness and interactive parameters.
Poster & Visual Design
anthropics
Create original posters and visual art in PNG and PDF formats.
Claude API Helper
anthropics
Build, debug, and optimize Claude API applications with caching and model migration support.
MCP Server Builder
anthropics
Build protocol servers that connect language models to external APIs and services.