Caveman: Token-Komprimierung für KI-Agents

1. Projektübersicht

Caveman ist ein Open-Source-Toolkit – bestehend aus einem Skill im Stil von Claude Code und einem lokalen Proxy –, das den Token-Verbrauch von KI-Coding-Agents reduziert, indem es sowohl die gelesenen Daten (Eingaben) als auch die erzeugten Antworten (Ausgaben) komprimiert, ohne dabei exakten Code, Fehlermeldungen oder wichtigen Kontext zu verlieren.

2. Hintergrund und Positionierung

Kernmission: Da agentic Coding-Sitzungen immer länger werden, füllen sich Kontextfenster schnell und die API-Kosten steigen entsprechend an. Die erklärte Philosophie von Caveman – „warum viele Token nutzen, wenn wenige genügen“ – zielt darauf ab, ausführliche Tool-Ausgaben, Logs, JSON und Diffs in Echtzeit zu verkleinern. So können Agents innerhalb desselben Budgets mehr leisten, wobei gleichzeitig garantiert wird, dass die ursprünglichen Bytes stets wiederherstellbar bleiben.
Zwei ergänzende Produkte: Der ursprüngliche Caveman-Skill macht die Antworten des Agents selbst knapper (in Benchmarks etwa 65 % Reduktion der Ausgabe-Tokens) gegen einen geringen Overhead pro Durchlauf. Caveman 2, der neuere lokale Proxy, fängt den Datenverkehr zum Provider ab und komprimiert Eingaben, bevor sie überhaupt den lokalen Rechner verlassen (ein fixierter Benchmark berichtet von 33,2 % weniger vom Provider gemeldeten Eingabe-Tokens).
Unterschiede zu ähnlichen Projekten: Anstatt zu versuchen, Inhalte zusammenzufassen oder umzuformulieren (was riskiert, exakten Code oder Stack-Traces zu verlieren), wendet Caveman eine inhaltsbewusste, verlustfrei sichere Komprimierung an. Eine Transformation wird nur dann angewendet, wenn sie nachweislich kleiner ist; zudem wird ein inhaltsadressiertes Original für die bytegenaue Wiederherstellung vorgehalten. Die eigene Dokumentation („Ehrliche Zahlen“) legt zudem offen dar, welche Einsparungen lokal geschätzt und welche unabhängig benchmarkt wurden.

3. Funktionskategorien

🗜️ Komprimierungs-Engine
Inhaltsbewusste Kompressoren für die Datentypen, mit denen Agents am häufigsten arbeiten:

Strukturelle JSON-Komprimierung (Schlüssel/Struktur/Fehlerbäume) – typischerweise 70–90 % Reduktion
Log-Komprimierung (Fehler, Traces, Abgrenzungen) – 85–95 %
Code-Komprimierung (Imports, Signaturen, Typen) – 40–70 %
Diff-Komprimierung (Header, geänderte Zeilen) – 60–80 %
Komprimierung von Suchergebnissen sowie Text/HTML – 50–95 %
Zweck: Die unruhigsten und repetitivsten Inhaltstypen verkleinern, bevor sie Kontext-Tokens verbrauchen.

🖼️ Pixel-Modus
Rendert dichten Text (gebündelte Tool-Kataloge, lange Logs) als PNG-Bilder für Modelle mit Bildverständnis. In einem dokumentierten Fall sank der Verbrauch dadurch von ca. 55.000 Text-Tokens auf ca. 11.000 Bild-Tokens (−79 %).
Zweck: Text-Tokens gegen Bild-Tokens tauschen, wenn ein Modell Bilder kostengünstiger verarbeiten kann als Rohtext.

🧠 Lernen und Analyse
Der Befehl caveman learn scannt den lokalen Verlauf eines Agents, um Token-Fresser zu identifizieren und Optimierungen zu klassifizieren.
Zweck: Konkrete, quantifizierte Einsparmöglichkeiten aufzeigen, ohne Daten extern zu versenden oder Kosten zu verursachen.

🔌 Agent-Integration
Native Unterstützung für Claude Code, OpenAI Codex CLI, Gemini CLI, Aider, opencode, Hermes Agent und OpenClaw sowie baseURL-Kompatibilität mit Frameworks wie Vercel AI SDK, LangChain, LiteLLM, CrewAI und PydanticAI – insgesamt über 30 Agents.
Zweck: Ermöglicht jeder bestehenden Agent-Umgebung das Routing über den komprimierenden Proxy mit minimalen oder keinen Codeänderungen.

🧰 CLI-Dienstprogramme
Eigenständige Befehle wie caveman shrink, caveman browse, caveman mem remember|recall und caveman toon encode|decode.
Zweck: Entwicklern direkten, skriptfähigen Zugriff auf dieselben Komprimierungsprimitiven außerhalb einer Agent-Sitzung bieten.

4. Wichtige Highlights

Bytegenaue Wiederherstellung: Für jede komprimierte Nutzlast werden die ursprünglichen Bytes vor der Komprimierung in einem inhaltsadressierten Speicher abgelegt, sodass nichts wirklich verloren geht.
Garantie „Nur komprimieren, wenn kleiner“: Transformationen laufen nur, wenn sie die Größe messbar reduzieren; Ablehnungen werden mit Begründung protokolliert, statt Inhalte stillschweigend zu verschlechtern.
Getrennte Eingabe-/Ausgabekomprimierung: Der Skill (Ausgaben) und der Proxy (Eingaben) können unabhängig voneinander eingeführt werden, sodass Teams mit dem beginnen können, der ihnen den größeren Mehrwert bietet.
Transparentes Benchmarking: Die Dokumentation „Ehrliche Zahlen“ unterscheidet zwischen lokal geschätzten Einsparungen und unabhängig gemessenen Benchmark-Ergebnissen, um übertriebene Behauptungen zu vermeiden.
Wählbare Intensitätsstufen: Der im Agent integrierte /caveman-Skill unterstützt mehrere Komprimierungsintensitäten (lite, full, ultra und eine „wenyan“-Variante), um unterschiedlichen Ausführlichkeitsanforderungen gerecht zu werden.
Breite Agent-Abdeckung: Funktioniert mit über 30 Agents und Frameworks durch native Integration oder einfache baseURL-Konfiguration, statt Nutzer an ein einzelnes Agent-Produkt zu binden.

5. Anwendungsfälle nach Rolle

Allgemeine Entwickler: Reduzieren Token-Kosten und Kontextaufblähung während alltäglicher agentic Coding-Sitzungen (Claude Code, Codex, Gemini CLI, Aider usw.), ohne ihre Prompting-Gewohnheiten ändern zu müssen.
DevOps/SRE: Komprimieren ausführliche CI-Logs, Befehlsausgaben und Diagnosedaten (caveman shrink -- [Befehl]), damit Agents Incidents innerhalb eines kleineren Kontextfensters analysieren können.
Daten-/Forschungswissenschaftler: Nutzen caveman learn, um den Sitzungsverlauf von Agents zu analysieren und zu quantifizieren, wo Tokens – und damit Kosten – tatsächlich anfallen, um Workflow-Anpassungen zu informieren.
Projektmanager: Greifen auf die Benchmark- und „Ehrliche Zahlen“-Dokumentation zurück, um realistische Erwartungen zur Kostensenkung zu bewerten, bevor Caveman im gesamten Team ausgerollt wird.

6. Erste Schritte

Finden, was Sie brauchen
Durchsuchen Sie das Verzeichnis docs/ für Architekturdetails, CLI-Referenzen, Sicherheits-/Datenschutzhinweise und Benchmark-Methodik, beginnend bei der README.md der Dokumentation.

Installieren / Integrieren

# Proxy (Caveman 2) — komprimiert Eingaben
npm install -g @caveman-ai/cli && caveman setup --install
caveman claude   # oder: codex, gemini, aider, hermes, openclaw

# Skill — komprimiert Ausgaben, wird im Skill-Verzeichnis eines Agents installiert
npx skills add JuliusBrussee/caveman

Beitragen

git commit -s -m "your message"   # DCO-Sign-off ist für jeden Commit erforderlich

Führen Sie die entsprechende Testsuite für das Paket aus, das Sie bearbeitet haben (go test ./..., pnpm test oder pytest), halten Sie PRs klein und fokussiert und erstellen Sie sie gegen das Haupt-Repository. Fragen können an [email protected] oder in eine GitHub-Diskussion gerichtet werden.

7. Projektstruktur

caveman/
├── agents/profiles/       # Definitionsdateien für Agent-Integrationen (Claude Code, Codex, Gemini CLI, ...)
├── integrations/recipes/  # Integrationsbeispiele für Provider-SDKs (LangChain, LiteLLM, ...)
├── engine/                # Komprimierungs-Engine und Rendering für den Pixel-Modus
├── browse/                # Implementierung der Browser-Inhaltskomprimierung
└── docs/                  # Architektur, CLI-Referenz, Benchmarks, Sicherheitsdokumentation

8. Zugehöriges Ökosystem

Upstream-Agents/Plattformen: Claude Code (Anthropic), OpenAI Codex CLI, Gemini CLI (Google), Aider, opencode, Hermes Agent (Nous Research), OpenClaw – Caveman integriert diese, statt sie zu ersetzen.
Ergänzende Frameworks: Vercel AI SDK, LangChain, LiteLLM, CrewAI und PydanticAI können über die Standard-baseURL-Konfiguration auf den Caveman-Proxy verweisen.
Gebündelte Drittanbieter-Komponenten: pxpipe (MIT), die Schriftart Spleen (BSD-2-Clause) und GNU Unifont (OFL-1.1 / GPLv2-mit-Schriftausnahme) werden intern verwendet, insbesondere für das Rendering im Pixel-Modus.

9. Lizenz

Caveman verwendet eine nach Verzeichnissen aufgeteilte Lizenz.

✅ Den Skill, das Agent-SDK, die CLI, Client-SDKs und Adoptions-Tools dürfen Sie unter der MIT-Lizenz frei nutzen, modifizieren und weiterverteilen.
✅ Die Engine, den Proxy, die Cache-Engine, den Rewriter, die Browse-Funktionalität und den MCP-Server dürfen Sie für Ihren eigenen First-Party-Datenverkehr unter BSL-1.1 kostenlos selbst hosten.
❌ Es ist nicht gestattet, die unter BSL-1.1 fallenden Komponenten (Engine/Proxy/MCP-Server) als von Dritten gehosteten oder eingebetteten Dienst anzubieten, ohne eine kommerzielle Lizenz des Projekts.
ℹ️ Der unter BSL-1.1 stehende Code wandelt sich automatisch in Apache-2.0 um, entweder am 21. Juni 2030 oder vier Jahre nach Veröffentlichung der jeweiligen Version, je nachdem, was zuerst eintritt.
ℹ️ GitHubs eigene Metadaten listen die Lizenz als „NOASSERTION“, da das geteilte MIT/BSL-1.1-Modell keinem einzelnen SPDX-Bezeichner entspricht – prüfen Sie die LICENSE-Dateien in jedem Verzeichnis für die tatsächlich geltenden Bedingungen.

10. FAQ

F: Korrumpiert oder verliert Caveman jemals stillschweigend Daten?
A: Nein – jede komprimierte Nutzlast behält eine inhaltsadressierte Kopie der ursprünglichen Bytes, und Transformationen werden nur angewendet, wenn sie messbar kleiner als die Eingabe sind; andernfalls wird die Ablehnung mit Begründung protokolliert.

F: Kann ich nur den ausgabekomprimierenden Skill ohne den Proxy verwenden oder umgekehrt?
A: Ja. Der Skill (npx skills add JuliusBrussee/caveman) und der Proxy (npm install -g @caveman-ai/cli) sind unabhängige Produkte und können separat eingeführt werden.

F: Welche Coding-Agents unterstützt Caveman?
A: Die native Integration umfasst Claude Code, OpenAI Codex CLI, Gemini CLI, Aider, opencode, Hermes Agent und OpenClaw. Insgesamt sind über 30 Agents erreichbar, einschließlich Frameworks, die via baseURL konfigurierbar sind.

F: Kann ich den Proxy/die Engine für mein eigenes Team selbst hosten?
A: Ja, das Self-Hosting für First-Party-Datenverkehr ist unter BSL-1.1 kostenlos; eine kommerzielle Lizenz ist nur erforderlich, um ihn als gehosteten oder eingebetteten Dienst für Dritte anzubieten.

F: Woher stammen die Benchmark-Zahlen (65 %, 33,2 %)?
A: Siehe docs/HONEST-NUMBERS.md und docs/WRAP-BENCHMARK.md, die zwischen lokal geschätzten Werten und unabhängig fixierten Benchmark-Ergebnissen unterscheiden.

11. Schnellzugriff

Repository: https://github.com/JuliusBrussee/caveman
Dokumentation: https://github.com/JuliusBrussee/caveman/tree/main/docs
Beitragsrichtlinien: https://github.com/JuliusBrussee/caveman/blob/main/CONTRIBUTING.md
Diskussionen / Kontakt: GitHub Discussions im Repository oder [email protected]

12. Zusammenfassung

Caveman bietet KI-Coding-Agents eine praktische Möglichkeit, weniger zu sagen und zu lesen, ohne etwas Wichtiges zu verlieren – durch die Kombination eines Skills für knappere Ausgaben mit einem lokalen Proxy zur Eingangskomprimierung, beide abgesichert durch Garantien zur bytegenauen Wiederherstellung. Es ist besonders wertvoll für Entwickler und Teams, die lange agentic Coding-Sitzungen mit Claude Code, Codex, Gemini CLI oder ähnlichen Tools durchführen und ihren Token-Verbrauch messbar senken möchten, ohne auf exakten Code, Fehlermeldungen oder Logs zu verzichten.