headroom について
Python または TypeScript アプリが大きなツール出力、ログ、JSON、検索結果、長いチャット履歴を LLM に送信し、入力トークン数やトークンコストの削減、コンテキストウィンドウへの適合、エラーを失わないツール結果の短縮が必要な場合に使用します。headroom-ai compress() 呼び出しを追加します。プロセス内で動作し、API キーもモデルのダウンロードも不要です。
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/headroomを入力して読み込まれたか確認します。
README（原文）English
プロジェクトの README よりこの 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_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