Mein lokales KI-Coding-Toolkit: Wie ich Agenten schnell und Token-effizient halte

Ammar Najjar · Veröffentlicht am 23. August 2026

productivitytoolsaiopencodeclaude-code

KI-generiertes Bild

KI-Coding-Agenten sind fest in meinen täglichen Arbeitsablauf integriert. Ich nutze OpenCode und Claude Code für unterschiedlichste Aufgaben: vom Einarbeiten in unbekannte Codebasen und der Fehleranalyse bis hin zur Umsetzung von Änderungen, Code-Reviews und der Arbeit an architektonischen Fragestellungen.

Mit intensivierter Nutzung dieser Werkzeuge stellte sich jedoch ein neuartiges Optimierungsproblem heraus.

Die Qualität des Modells ist entscheidend, aber das direkte Umfeld ist es ebenso.

Ein Agent kann unbemerkt eine erhebliche Menge an Token verbrauchen. Er liest vollständige Dateien, obwohl nur ein kleiner Ausschnitt relevant ist. Er führt Befehle aus, die hunderte Zeilen Output erzeugen. Er durchsucht dieselbe Codebasis mehrfach oder schleppt veraltete Informationen durch eine lange Session. Für sich genommen wirken diese Ineffizienzen gering, über dutzende Operationen hinweg summieren sie sich jedoch schnell.

Aus diesem Grund habe ich begonnen, die Systemumgebung rund um den Agenten gezielt zu optimieren.

Dieser Beitrag beschreibt das lokale Toolkit, das ich derzeit einsetze, die Aufgaben der einzelnen Werkzeuge und das Zusammenspiel zur Vermeidung unnötiger Kontextbelastung.

Meine aktuelle Werkzeugauswahl

So greifen die einzelnen Komponenten derzeit ineinander:

Das Ziel besteht nicht in einer möglichst großen Anzahl an Werkzeugen.

Entscheidend ist eine klare Aufgabenverteilung. Der verbleibende Beitrag erläutert die Funktionsweise und den konkreten Nutzen der jeweiligen Komponenten.

Das Problem: Agenten verbrauchen mehr Ressourcen als gedacht

Ein Coding-Agent leistet weit mehr als die reine Codegenerierung.

Betrachten wir eine typische Aufgabenstellung:

Find where this value is calculated, understand the implementation,
change the behavior, and verify the result.

Hierbei muss der Agent relevante Dateien identifizieren, nach Symbolen suchen, Code analysieren, die Implementierung anpassen, Builds ausführen, Ausgaben prüfen und das finale Diff bewerten.

Jede dieser Operationen erweitert den Kontext des Modells.

Bereits ein einfacher Befehl wie:

git diff

kann bei umfangreichen Änderungen tausende Token erzeugen. Oder:

cat some-large-file.ts

obwohl lediglich ein kleiner Abschnitt der Datei benötigt wird.

Diese einzelnen Ineffizienzen erscheinen isoliert vernachlässigbar, summieren sich im Verlauf einer langen Session jedoch erheblich.

Daraus ergibt sich folgende Zielsetzung:

Versorge den Agenten mit der minimal notwendigen Informationsmenge, die für die nächste korrekte Entscheidung erforderlich ist.

Dieses Prinzip bildet das Fundament meines aktuellen Toolkits.

Der Kern: OpenCode und Claude Code

Als primäre Coding-Agenten nutze ich OpenCode und Claude Code.

In einem früheren Beitrag habe ich meine Erfahrungen mit OpenCode beim Ausführen lokaler KI auf meinem MacBook Pro dokumentiert. Eine wesentliche Erkenntnis war, dass die Handlungsfähigkeit des Agenten ebenso schwer wiegt wie die reine Modellleistung. Ein Modell, das zuverlässig in einem Repository navigieren, Werkzeuge bedienen, Code editieren und Workflows ausführen kann, bietet oft höheren praktischen Nutzen als ein Modell mit reinen Spitzenwerten in Coding-Benchmarks.

Gleiches gilt für die gesamte Peripherie des Agenten.

Jedes Werkzeug in der Übersicht erfüllt einen definierten Zweck. Bei der Code-Exploration entscheidet die Art der benötigten Information über das Werkzeug:

Text             → rg
Code-Struktur    → ast-grep
Code-Semantik    → Serena

Der Agent soll nicht schrittweise alle Optionen testen, sondern direkt das passende Werkzeug wählen.

Kontext- und Ausgabe-Management

Der erste Bereich adressiert die primäre Ursache für die Optimierung: die Reduzierung von Token- und Kontextverlusten.

Headroom: Steuerung des Kontextwachstums

Coding-Agenten akkumulieren kontinuierlich Kontext aus Befehlsausgaben, Dateiinhalten, Werkzeugaufrufen und vorherigen Interaktionen.

Nach längerer Laufzeit enthält ein erheblicher Teil des Kontextfensters Informationen, die zu Beginn nützlich waren, für die aktuelle Entscheidung jedoch keinen Mehrwert mehr bieten.

Headroom reduziert das Datenvolumen des angesammelten Kontextes, das für das Modell vorgehalten werden muss, während aufgabenrelevante Details erhalten bleiben. Dadurch lassen sich auch längere Sessions produktiv nutzen, ohne den gesamten bisherigen Verlauf in vollem Umfang mitführen zu müssen.

Ich betrachte Headroom als reine Komponente für das Kontextmanagement, nicht als operatives Coding-Werkzeug.

Diese Differenzierung ist wesentlich: Headroom ersetzt weder die Repository-Suche noch die Code-Analyse, sondern verringert die Ressourcenkosten der Bereitstellung dieser Informationen über die gesamte Session hinweg.

RTK: Reduzierung von Befehlsausgaben

RTK (Rust Token Killer) minimiert das Datenvolumen von Shell-Ausgaben.

Anstelle von:

git status

führt der Agent bevorzugt folgenden Befehl aus:

rtk git status

Dieses Muster lässt sich auf Builds, Logs, GitHub-CLI-Aufrufe, Docker, Kubernetes sowie zahlreiche weitere Terminal-Befehle übertragen:

rtk git diff
rtk gh pr view 123
rtk bun run build
rtk docker logs my-container

Ein Detail war bei der Konfiguration entscheidend: RTK bestimmt nicht die Auswahl des eigentlichen Werkzeugs.

Der Agent wählt primär das jeweils optimale Werkzeug aus; RTK umschließt dieses im Anschluss.

Beispiel:

rtk rg "PaymentService" src/

Die Suchfunktionalität von ripgrep bleibt vollständig erhalten, während RTK die zurückgegebene Datenmenge für den Agenten filtert.

Der Ablauf folgt diesem Schema:

Passendes Werkzeug auswählen
        ↓
Über RTK ausführen
        ↓
Nur relevante Ausgaben zurückgeben

Caveman: Prägnante Agenten-Antworten

Token-Verbrauch entsteht nicht ausschließlich durch Werkzeugausgaben, sondern auch durch Antworten des Agenten selbst.

Ausführliche Erklärungen sind bei Einarbeitungen oder Architekturdiskussionen hilfreich, erzeugen jedoch unnötigen Overhead, wenn lediglich ein Attribut umbenannt, ein Symbol lokalisiert oder ein überschaubarer Fehler behoben werden soll.

Caveman sorgt in diesen Fällen für kurze, fokussierte Antworten.

Diese drei Werkzeuge decken jeweils spezifische Abschnitte desselben Problems ab:

Headroom → Kontext
RTK      → Befehlsausgabe
Caveman  → Agenten-Antworten

Das bildet die Basis des Setups.

Code-Exploration und Verständnis

Die nächste Herausforderung betrifft die effiziente Navigation des Agenten innerhalb der Codebasis.

Das vollständige Einlesen von Dateien verursacht meist höhere Kosten als das gezielte Auffinden der benötigten Information.

ripgrep: Textbasierte Suche

Für gewöhnliche Textrecherchen gehört rg zu den effektivsten Werkzeugen im System.

Liegen konkrete Zeichenketten, Konfigurationswerte, Fehlermeldungen oder Bezeichner vor, kann der Agent diese direkt ansteuern:

rtk rg "localizedUrl" src/

Die Suche lässt sich zudem präzise einschränken:

rtk rg "localizedUrl" src/ --type ts

Das vermeidet das schrittweise Öffnen und Durchsuchen einzelner Verzeichnisse.

fd: Dateipfade ermitteln

fd übernimmt für Dateipfade dieselbe Funktion wie rg für Dateiinhalte.

Ist der ungefähre Dateiname bekannt, startet der Agent mit einer gezielten Abfrage:

rtk fd cloudflare

oder:

rtk fd '\.astro$' src/

Die Leitlinie lautet: Zuerst lokalisieren, danach lesen.

ast-grep: Strukturelle Suche im Code

Oft gesuchte Elemente sind keine reinen Textmuster, sondern spezifische Konstrukte der Programmiersprache.

Reguläre Ausdrücke stoßen hier schnell an Grenzen, da Quellcode einer festen Syntax und Struktur folgt.

An dieser Stelle setzt ast-grep an.

Es kommt bei strukturellen Fragestellungen zum Einsatz: bestimmten Funktionsaufrufen, Syntaxmustern, Deklarationen oder Elementen, bei denen eine Analyse des abstrakten Syntaxbaums (AST) präzisere Ergebnisse liefert als eine reine Textsuche.

Es schließt die Lücke zwischen reiner Textsuche und vollständiger semantischer Code-Navigation.

Serena: Semantische Code-Navigation

Serena deckt Anwendungsfälle ab, in denen das semantische Codemodell im Vordergrund steht.

Typische Fragestellungen:

Wo ist dieses Symbol definiert?

Welcher Code referenziert diese Klasse?

Welche Implementierungen existieren für dieses Interface?

Wie stehen diese Symbole zueinander in Beziehung?

Ohne semantische Werkzeuge müsste ein Agent nach Symbolen suchen, mehrere Dateien öffnen, Importe analysieren, erneut suchen und Zusammenhänge manuell rekonstruieren.

Serena liefert diese Strukturbeziehungen direkt.

Die Differenzierung zwischen Text, Struktur und Semantik hat sich in der Praxis bewährt. Ziel ist nicht die Abdeckung aller Aufgaben durch ein einzelnes Werkzeug, sondern die Vermeidung unnötiger Suchvorgänge durch die Auswahl des jeweils optimalen Tools.

Strukturierte Daten und GitHub

Selbst kleine, hochspezialisierte Werkzeuge können erhebliche Mengen an unnötigem Kontext einsparen.

jq und yq

Agenten arbeiten regelmäßig mit JSON- und YAML-Dateien: Package-Konfigurationen, API-Antworten, Kubernetes-Manifesten oder GitHub-Actions-Workflows.

Wird nur eine einzelne Eigenschaft aus einem JSON-Dokument benötigt, ist das Laden des gesamten Dokuments in den Kontext ineffizient.

Stattdessen:

rtk jq '.scripts' package.json

Für YAML:

rtk yq '.jobs' .github/workflows/build.yml

Das Prinzip lautet:

Informationen gezielt extrahieren, statt vollständige Dokumente zu lesen.

Besonders bei umfangreichen API-Antworten ist dieser Ansatz wirkungsvoll.

gh: GitHub-Integration im Terminal

Die GitHub-CLI ermöglicht dem Agenten die Abfrage von Pull Requests, Issues, Workflow-Läufen und Repository-Daten direkt aus dem Terminal:

rtk gh pr list
rtk gh pr view 123
rtk gh run list

Auch hier gilt das Gebot gezielter Abfragen.

Das Abrufen einer vollständigen Diskussion zu einem Pull Request ist unnötig, wenn lediglich dessen Status benötigt wird. Gleiches trifft auf Workflow-Logs und Issue-Historien zu.

Die Kombination aus gh und jq erlaubt sehr präzise Datenabfragen.

Nicht jedes Entwickler-Werkzeug eignet sich für Agenten

Der Einsatz von bat, delta und fzf verdeutlichte einen wesentlichen Unterschied:

Ein effizientes Werkzeug-Setup für Entwickler ist nicht automatisch optimal für autonome KI-Agenten.

Agenten profitieren vorrangig von deterministischen Befehlen, strukturierten Daten und klar begrenzten Ausgaben.

Menschliche Entwickler bevorzugen visuelle Aufbereitung, interaktive Navigation, Syntax-Highlighting und Fuzzy-Auswahlen.

Aus diesem Grund nutze ich persönlich:

• bat für die übersichtliche Dateiinspektion mit Zeilennummern und Syntax Hervorhebung.
• delta für gut lesbare Git-Diffs.
• fzf für das interaktive Filtern von Dateien, Branches, Historien und Suchergebnissen.

Diese Werkzeuge sind im Terminal-Alltag äußerst nützlich, müssen dem autonomen Agenten jedoch nicht zwingend bereitgestellt werden.

Beispielsweise ist fzf ideal, wenn ich manuell eine Datei oder einen Branch auswähle. Ein autonomer Agent arbeitet mit einer deterministischen Abfrage über fd, rg oder jq deutlich effizienter.

Diese Abgrenzung wird bei der Konfiguration von KI-Umgebungen häufig übersehen.

Mehr Werkzeuge führen nicht automatisch zu höherer Effizienz des Agenten.

AGENTS.md: Das Zusammenspiel der Werkzeuge definieren

Die Installation der Werkzeuge erfordert wenig Aufwand.

Die eigentliche Herausforderung besteht darin, dem Agenten die koordinierte Nutzung beizubringen. Dies erfordert initiale Vorbereitung: das Erstellen der AGENTS.md, das Testen der Werkzeugnutzung sowie die Anpassung der Regeln anhand der tatsächlichen Token-Ersparnis in der Praxis. Sobald die Konfiguration steht, gelten diese Vorgaben automatisch als Standard für künftige Sessions.

Zu diesem Zweck pflege ich eine zentrale AGENTS.md, die die Systemumgebung, Projektkonventionen, Regelsätze zur Werkzeugauswahl, Verifikationsanforderungen und Effizienzprinzipien definiert.

Dies stellt die allgemeine Ebene dar. Auf Projektebene lässt sich dieses Prinzip vertiefen. In meinen Angular-Projekten zeigte sich beispielsweise, wie klare Architekturvorgaben und Konventionen für KI-Agenten die Ergebnisqualität signifikant steigern. Das Toolkit in diesem Beitrag strukturiert die Umgebung, während der projektspezifische Kontext die Fachdomäne abdeckt.

Es reicht nicht aus, dem Agenten lediglich die vorhandenen Werkzeuge aufzuzählen:

You have rg.
You have ast-grep.
You have Serena.

Wichtig ist die Definition konkreter Zuständigkeiten und Einschränkungen.

Der Agent muss den genauen Informationsbedarf ermitteln, das geeignete Werkzeug wählen, die Ergebnismenge begrenzen und den Suchvorgang beenden, sobald ausreichend Evidenz vorliegt.

Das verhindert ein bekanntes Fehlverhalten: das wiederholte Durchsuchen desselben Problems mit unterschiedlichen Werkzeugen, nur weil diese verfügbar sind.

Session-Management: Strategien jenseits der Werkzeuge

Werkzeuge wie Headroom, RTK und Caveman reduzieren den Token-Verbrauch innerhalb einer laufenden Session. Ein erheblicher Teil der Ersparnis resultiert jedoch aus der klaren Strukturierung der Sessions selbst.

Kompaktierung (Compacting)

Sowohl OpenCode als auch Claude Code unterstützen die Kompaktierung von Sessions. Bei langen Gesprächsverläufen lässt sich die Historie zusammenfassen, um den Kontextfensterbereich zu bereinigen.

Diese Funktion ergänzt Headroom, indem sie den akkumulierten Gesprächsverlauf periodisch reduziert. Ich nutze sie bei aktiven Aufgaben mit bereits umfangreicher Session-Historie. Ältere Werkzeugausgaben, Dateiinhalte und Zwischenschritte werden in eine kompakte Form überführt, die wesentliche Entscheidungen und Daten bewahrt.

Das ist besonders wertvoll, wenn eine Aufgabe noch nicht abgeschlossen ist, der Verlauf jedoch stark anwächst. Statt die Arbeit neu zu starten, wird die Session kombiniert und fortgeführt.

Neue Sessions für neue Aufgaben

Beim Wechsel zu einer grundlegend neuen Aufgabenstellung starte ich konsequent eine frische Session.

Eine lange Session trägt Altlasten vorheriger Arbeitsschritte mit sich. Diese Informationen sind für die neue Aufgabe irrelevant, belasten aber weiterhin das Modell. Ein Neustart stellt sicher, dass ausschließlich aufgabenrelevanter Kontext vorhanden ist.

Vergleichbar mit dem Reinigen einer Tafel: Frühere Notizen waren nützlich, erzeugen bei neuen Problemstellungen jedoch Ablenkung.

Aufgabenstrukturierung (Task Decomposition)

Komplexe Aufgabenstellungen zerlege ich in fokussierte Phasen, statt alles in einem einzelnen Durchgang abzufragen. Ein Session-Neustart erfolgt jedoch nicht zwingend nach jedem Teilschritt; zusammenhängende Phasen profitieren vom bestehenden Kontext. Ein Wechsel erfolgt erst, wenn der bisherige Verlauf keinen Mehrwert mehr liefert.

Die Entscheidung folgt diesem Schema:

Zusammenhängende Arbeit mit nutzbarem Kontext
→ Session fortführen

Neue oder grundlegend abweichende Aufgabe
→ Frische Session starten

Beispiel: Das Analysieren eines Moduls und das anschließende Beheben eines Fehlers darin stehen in direktem Zusammenhang. Der Analysekontext ist für die Korrektur unmittelbar nutzbar. Der Wechsel zu einem unbezogenen Feature oder einem anderen Modul stellt dagegen eine neue Aufgabe dar, die in einer frischen Session effizienter bearbeitet wird.

Präzise Prompts

Die Formulierung der Aufgabenstellung hat direkten Einfluss auf den Such- und Iterationsaufwand des Agenten.

Ein vager Prompt wie:

Fix the login issue

zwingt den Agenten zu breiter Exploration, dem Einlesen mehrerer Dateien und eigenen Annahmen.

Ein präziser Prompt wie:

Investigate the OAuth token refresh failure in src/auth/.
Identify the cause, make the smallest necessary change,
and verify the build.

gibt ein hohes Maß an Orientierung und ein klar abgegrenztes Ziel vor. Das Resultat: weniger Suchvorgänge, reduzierte Werkzeugaufrufe und geringerer Kontextverbrauch.

Es ist eine der simpelsten und zugleich effektivsten Optimierungen.

Ein Werkzeug unter Beobachtung: Context Mode

Ein interessant konzipiertes Werkzeug ist Context Mode. Es verfolgt den Ansatz, große Werkzeugausgaben außerhalb des Modellkontextes zu halten und Informationen erst bei konkretem Bedarf abzurufen. Die Idee eines durchsuchbaren, persistenten Session-Kontextes ist insbesondere für lange Entwicklungssessions relevant.

Diese Zielsetzung deckt sich mit meinem Ansatz, überschneidet sich jedoch mit Headroom, RTK und den Vorgaben meiner AGENTS.md. Eine zusätzliche Schicht für das Kontextmanagement führt nicht automatisch zu höherer Effizienz, sondern kann redundantes Verhalten oder widersprüchliche Instruktionen erzeugen.

Aktuell:
Headroom + RTK + Serena + Caveman

Alternative:
Context Mode + RTK + Serena + Caveman

Die entscheidende Frage lautet, ob Context Mode Teile des bestehenden Setups in langen Sessions funktionell ersetzen oder übertreffen kann. Eine finale Bewertung erfordert empirische Benchmarks; diese Einschätzung basiert auf der Analyse des Projektkonzepts.

Context Mode bietet einen interessanten Ansatz für eigene Tests, stellt jedoch eher eine potenzielle Alternative zu Teilen des bestehenden Setups dar als eine zusätzliche Ergänzung.

Die wichtigste Regel: Abbruchkriterien definieren

In der Praxis zeigt sich, dass die Auswahl der Werkzeuge nur eine Seite der Medaille ist.

Ebenso wichtig ist das Wissen des Agenten, wann ein Werkzeug nicht mehr eingesetzt werden soll.

Meine AGENTS.md enthält daher eindeutige Abbruchregeln:

Stop searching once enough evidence exists.

Do not inspect additional files merely for completeness.

Do not repeat a successful search using another tool.

Do not continue repository exploration after finding the relevant implementation.

After successful verification, stop unless additional verification is justified.

Diese Regeln gehören zu den wirksamsten Optimierungen im gesamten System.

Selbst ein Agent mit optimaler Werkzeugausstattung verbraucht unnötig Ressourcen, wenn er diese ohne klare Abbruchkriterien einsetzt.

Fazit

Der anfängliche Reflex, kontinuierlich neue Werkzeuge zu ergänzen, wich der Erkenntnis, dass klare Systemgrenzen entscheidend sind.

Einige Werkzeuge weisen zwar funktionale Überschneidungen auf, operieren jedoch auf unterschiedlichen Systemebenen. Andere sind für die manuelle Arbeit im Terminal wertvoll, bieten einem autonomen Agenten jedoch keinen Vorteil. Entscheidend ist nicht die Maximierung von Funktionen, sondern die gezielte Steuerung des Informationsflusses.

Mein aktueller Ansatz lässt sich in fünf Grundregeln zusammenfassen:

1. Werkzeugauswahl strikt an der benötigten Informationsart ausrichten.
2. Suchen und Lokalisieren vor dem Einlesen von Dateien.
3. Ausschließlich die minimal erforderliche Informationsmenge zurückliefern.
4. Umfangreiche Terminal-Ausgaben komprimieren.
5. Suchvorgänge sofort beenden, sobald ausreichend Evidenz vorliegt.

Die konkreten Werkzeuge werden sich im Laufe der Zeit verändern; das zugrunde liegende Prinzip bleibt bestehen:

Eine leistungsfähige KI-Entwicklungsumgebung zeichnet sich nicht nur durch umfangreiche Fähigkeiten des Agenten aus, sondern vor allem durch die Kontrolle darüber, wie viele Informationen zur Aufgabenerfüllung benötigt werden.

Dieser Wandel hin zu einem bewussten Informationsmanagement hat die Effizienz meines lokalen KI-gestützten Entwicklungs-Workflows nachhaltig gesteigert.

Falls du KI-Coding-Agenten lokal betreibst, interessieren mich deine Ansätze und Erfahrungen. Jedes Setup unterscheidet sich, und praxisnahe Einblicke bieten oft wertvolle Optimierungsansätze.

Verwandte Beiträge

• Lokale KI auf einem MacBook Pro mit 16 GB RAM: Was in der Praxis funktioniert
• Essenzielle Entwickler-Tools: Mein Brewfile-Setup

Nach oben