Headroom installieren: Context-Kompression für Claude Code einrichten

Lange Coding-Sessions laufen irgendwann ins Context-Limit. Gelesene Dateien, Tool-Ausgaben und der bisherige Verlauf füllen das Fenster, und ab einem gewissen Punkt bremst genau das die Arbeit. Headroom setzt hier an. Das Werkzeug legt sich lokal zwischen deinen Coding-Agenten und das Sprachmodell und verdichtet, was gelesen wird, bevor es beim Modell ankommt.

Headroom läuft dabei komplett auf deinem Rechner, deine Daten verlassen die Maschine nicht. In diesem Beitrag installierst du Headroom von Grund auf, hängst es an Claude Code und prüfst, ob wirklich etwas eingespart wird. Wir zeigen dir zwei gleichwertige Wege, den offiziellen CLI-Weg und den Claude-Code-Plugin-Weg, damit du den nimmst, der zu deinem Setup passt.

Was du am Ende davon hast

• Eine lokale Kompressionsschicht, die Kontext verdichtet, bevor er Tokens kostet.

• Claude Code läuft weiter wie gewohnt, Headroom arbeitet im Hintergrund.

• Ein Dashboard, das dir schwarz auf weiß zeigt, wie viele Tokens tatsächlich wegfallen.

• Ein Setup, das sich sauber wieder entfernen lässt, wenn es für deine Arbeitsweise nichts bringt.

Voraussetzungen

• Python 3.10 oder neuer. Für die Dollar-Anzeige im Dashboard empfiehlt sich Python 3.13.

• Eine CPU mit AVX2 (x86_64) oder Apple Silicon. Für andere Architekturen gibt es Fallback-Pfade.

• Claude Code als installierter Coding-Agent. Headroom wrappt auch Codex, Cursor, Aider und weitere.

• Grundvertrautheit mit dem Terminal. Alle Befehle laufen in der Kommandozeile.

Schritt 1: Headroom installieren

Am schnellsten geht die Installation über uv, den modernen Python-Paketmanager. Wer lieber bei pip bleibt, nimmt die zweite Zeile. Beide holen die vollständige Version mit Kommandozeilen-Werkzeug.

uv unter Windows installieren, falls noch nicht vorhanden

Wenn uv auf deinem Windows-Rechner noch fehlt, holst du es mit einem Einzeiler in der PowerShell. Der Befehl lädt das offizielle Installationsskript von Astral und führt es direkt aus.

Schritt 2: Claude Code mit Headroom wrappen

Der kanonische Weg ist ein einziger Befehl. Er startet einen lokalen Proxy, richtet den MCP-Server ein und öffnet eine Claude-Code-Session, die ihre Anfragen über Headroom leitet.

Ab jetzt arbeitest du wie immer in Claude Code, nur dass jede Anfrage vorher durch die Kompression läuft. Denselben Weg gibt es auch für andere Agenten, etwa headroom wrap codex oder headroom wrap aider.

Alternative: als Claude-Code-Plugin

Wer Headroom direkt in Claude Code verwalten will, fügt den offiziellen Marketplace hinzu und installiert das Plugin danach über das Plugin-Menü. Der Weg ist bequemer, bleibt aber auf Claude Code beschränkt.

Danach öffnest du in Claude Code das Menü mit /plugin, wählst Headroom aus dem hinzugefügten Marketplace und installierst es. Ein Neustart der Session lädt das Plugin.

Schritt 3: Health-Check

Bevor du dich auf die Kompression verlässt, prüfst du, ob das Routing sauber steht. Headroom bringt dafür eigene Diagnosebefehle mit.

Der Befehl headroom doctor bestätigt, dass die Verbindung funktioniert und die Kompression greift. Meldet er einen Fehler, findest du im nächsten Abschnitt die häufigsten Ursachen.

Schritt 4: Ersparnis sichtbar machen

Headroom zeigt dir in einem lokalen Dashboard, wie viel gerade eingespart wird. Der Proxy muss dafür laufen.

Innerhalb einer laufenden Session kannst du zusätzlich das MCP-Werkzeug headroom_stats abrufen. Es zeigt, wie viele Anfragen komprimiert wurden und wie viele Tokens dabei weggefallen sind. Zwei weitere Werkzeuge stehen bereit: headroom_compress verdichtet Kontext, headroom_retrieve holt komprimierte Inhalte bei Bedarf wieder zurück.

Optional: mehr herausholen und wieder entfernen

Standardmäßig verdichtet Headroom, was das Modell liest. Es kann zusätzlich steuern, wie ausführlich das Modell zurückschreibt. Diese Funktion aktivierst du über eine Umgebungsvariable, bevor du den Proxy startest.

Auf macOS und Linux setzt du die Variable stattdessen mit export HEADROOM_OUTPUT_SHAPER=1. Möchtest du Headroom wieder loswerden, hebt ein Befehl das Wrapping sauber auf.

Häufige Probleme und Lösungen

Bricht pip install mit Zertifikatsfehlern ab, steckt meist ein Firmennetz mit SSL-Inspektion dahinter. Am zuverlässigsten hilft, die vorgebauten Wheels zu erzwingen, statt lokal zu kompilieren.

Scheitert der Start an strenger X.509-Prüfung im Firmennetz, lockerst du die Prüfung gezielt für den Proxy. Unter Windows setzt du dafür $env:HEADROOM_TLS_STRICT = "0" vor dem Start, auf macOS und Linux entsprechend per export.

Meldet die Installation, dass die Python-Version zu alt ist, brauchst du mindestens 3.10. Für die vollständige Kostenanzeige im Dashboard lohnt sich der Sprung auf 3.13.

Läuft der Proxy nur langsam oder gar nicht, prüfe die CPU. Ohne AVX2 greifen Fallback-Pfade, die weniger effizient sind. Auf Apple Silicon läuft die native arm64-Variante.

Wie viel bringt das wirklich

Bleiben wir ehrlich, denn die Zahlen hängen stark davon ab, womit du arbeitest. Bei rohen JSON-Daten und großen Tool-Ausgaben nennt das Projekt 60 bis 95 Prozent weniger Tokens. Beim reinen Coding-Alltag sind es realistischere 15 bis 20 Prozent.

In unserem eigenen Stack fällt der Durchschnitt niedriger aus, und das hat einen einfachen Grund. Bei uns kürzt RTK, der Rust Token Killer, Tool-Ausgaben und Dev-Kommandos schon, bevor sie überhaupt im Kontext landen. Headroom greift danach und holt aus dem Rest noch etwas heraus. Der große Batzen ist also längst weg, wenn Headroom seinen Teil beisteuert. Der Nutzen wächst spürbar mit der Größe deiner Kontexte: Wer lange Sessions mit vielen großen Dateien fährt, profitiert am ehesten.

Fazit

Headroom ist in wenigen Minuten installiert und stellt sich mit einem einzigen Befehl vor Claude Code. Der Aufwand lohnt sich vor allem für lange Sessions mit dicken Kontexten, und dank Dashboard musst du den Effekt nicht glauben, sondern kannst ihn ablesen. Wer nach dem ersten Test merkt, dass für die eigene Arbeitsweise wenig hängen bleibt, entfernt das Wrapping mit einem Befehl wieder.

Wenn du dein Setup rund um KI-gestütztes Coding gerade erst aufbaust und dabei über Standard-Werkzeuge hinaus willst, etwa eigene MCP-Server oder maßgeschneiderte Automatisierung, hilft dir unser Custom-Coding weiter. Das Grundmuster, einen lokalen Server einzubinden und den Client danach neu zu starten, kennst du übrigens schon aus unserer Anleitung zum MCP-Setup mit Claude und Obsidian. Fragen dazu? Melde dich.