← Zurück zur Startseite
Open Source · Context Compression

Headroom
Token sparen bei KI-Agenten

Headroom ist ein quelloffenes Tool, das den Kontext komprimiert, bevor er das Sprachmodell erreicht: Tool-Ausgaben, Logs, RAG-Chunks, Dateien und Gesprächsverlauf. Laut Projekt sinkt der Token-Verbrauch um 60–95 % – bei gleicher Antwortqualität. Funktioniert mit Claude Code, Codex und weiteren Agenten.

GitHub-Repository PyPI: headroom-ai

Kontext an das LLM

Ohne Headroom
100 %
Mit Headroom
~20 %

Weniger Tokens bedeuten weniger Kosten, mehr Platz im Kontextfenster und oft schnellere Antworten – ohne den Inhalt zu verlieren.

Was ist Headroom?

Eine Kompressions-Schicht zwischen Agent und Modell. Sie kürzt große Inhalte intelligent ein, statt sie ungefiltert in den Prompt zu schreiben.

Warum interessant?

KI-Agenten verbrennen die meisten Tokens mit langen Tool-Ausgaben und Logs. Headroom senkt genau diese Kosten – spürbar bei intensiver Nutzung.

Typische Nutzung

Als Bibliothek im Code, als transparenter Proxy, als MCP-Server oder als Wrapper um einen bestehenden Coding-Agenten wie Claude Code oder Codex.

Installation & Einsatz

Headroom ist als PyPI-Paket headroom-ai verfügbar (Python 3.10+) und lässt sich auf mehrere Arten einsetzen. Am einfachsten ist der Wrapper-Modus: ein einziges Kommando legt sich um deinen Coding-Agenten. Die folgenden Befehle stammen aus dem offiziellen Repository.

🤖 Claude Code Wrapper

1. Headroom installieren, 2. Claude Code damit umhüllen. Headroom komprimiert den Kontext dann automatisch im Hintergrund.

# 1. Headroom installieren (Python 3.10+) pip install "headroom-ai[all]" # 2. Claude Code mit Headroom starten headroom wrap claude

⚡ Codex (OpenAI) Wrapper

Gleiches Prinzip für die Codex-CLI: einmal installieren, dann Codex über Headroom aufrufen.

# 1. Headroom installieren pip install "headroom-ai[all]" # 2. Codex mit Headroom starten headroom wrap codex

🔌 MCP-Server

Headroom als MCP-Server registrieren – nutzbar in jedem MCP-fähigen Client.

headroom mcp install

🌐 Proxy-Modus

Transparenter Proxy ohne Code-Änderung – davor schalten und API-Calls laufen lassen.

headroom proxy --port 8787

📦 Als Bibliothek

Direkt in eigenen Python-Code einbinden und gezielt komprimieren.

# Python from headroom import compress

💻 Node / TypeScript

Für JavaScript-/TypeScript-Projekte gibt es das gleichnamige npm-Paket.

npm install headroom-ai
Hinweis: In Unternehmensumgebungen mit SSL-Inspektion sollte vor pip install ggf. Rust installiert sein (einige Komponenten werden lokal kompiliert). Die genauen Optionen stehen im README des Repositorys.

Gut zu wissen

Lizenz

Apache 2.0

Frei nutzbar, auch kommerziell. Entwickelt von chopratejas (Tejas Chopra).

Worum es technisch geht

Kompression

Komprimiert Tool-Outputs, Logs, RAG-Chunks, Dateien und Verlauf – nicht die eigentliche Antwort an dich.

Kompatibel mit

Agenten

Claude Code, Codex, Cursor, Aider, Copilot CLI und OpenAI-kompatible Clients.

Kurz gesagt: Headroom lohnt sich, wenn ein KI-Agent viel mit großen Datei-, Log- oder Suchausgaben arbeitet – dort entstehen die meisten unnötigen Tokens.
DatenschutzImpressum