headroom
/headroom
Ogranicza liczbę tokenów wejściowych w aplikacjach Python lub TypeScript, kompresując duże wyniki narzędzi i logi bez gubienia błędów.
- Autor
- tuan2304 ↗
- Repozytorium
- my-company ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 13.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 3
Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Ogranicza liczbę tokenów wejściowych w aplikacjach Python lub TypeScript, kompresując duże wyniki narzędzi i logi bez gubienia błędów.
Oryginalny opis (EN)
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.
Jak działa
- When this applies
- Python (in-process, no network)
- TypeScript
- Coding agents
- Do not
Podgląd SKILL.md
---
name: headroom
description: 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.
---
# 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)
```bash
pip install headroom-ai # add to requirements.txt / pyproject
```
```python
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:
```bash
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
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · tuan2304/my-company | 100 | MIT |
| TerminalSkills/skills | 100 | Apache-2.0 |
| momori777/artemis | 100 | Apache-2.0 |
| udaysharmadev/Skills | 100 | MIT |
| akillness/jeo-skills | 95 | MIT |
| roman-ryzenadvanced/headroom-skill | 95 | Apache-2.0 |
Migawka bazy z 13.11.2026 · wersja paczki 26fcf94f7eec (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 90tokenarmy
Ogranicza zużycie tokenów wejściowych i wyjściowych w zadaniach kodowania i agentowych bez utraty dokładności. - 90supercompress
Kompresuje duże wyniki narzędzi, pliki, logi i wklejone dokumenty przy pomocy compress_context, przed pracą sprawdzając limity. - 87context-compress
Przetwarza duże wyniki, logi, JSON i migawki stron narzędziami context-compress zamiast zwykłego Bash i cat. - 90supercompress
Kompresuje duże wyniki narzędzi, logi, diffy i wklejone dokumenty, nigdy nie kompresując prośby użytkownika, i pilnuje limitów. - 96agentvigor-token-budget
Ogranicza zużycie kontekstu agenta przez duże logi, szerokie wyszukiwania i powtarzające się wyniki narzędzi. - 90common-context-optimization
Zarządza kontekstem i kosztami cache promptów bez utraty stanu zadania: budżety tokenów, duże wyjścia narzędzi, chybienia cache i długie rozmowy.