tgrep-ai-skill/README.md

tgrep AI Skill

Lokale, indexierte Suche für Claude Code und Codex – mit frei wählbaren Verzeichnissen und optionalen Antworten von Qwen über Ollama.

Ein gemeinsamer Skill, eine CLI, gemeinsame Indizes. tgrep sucht Text und Code; Qwen übersetzt Fragen in Suchbegriffe und beantwortet sie anhand gefundener Ausschnitte. Die Hauptmodelle von Claude und Codex werden dabei nicht ersetzt.

Installation

Voraussetzungen: macOS oder Linux (ARM64/x86_64), Git, Python 3.10+ mit venv. Windows: innerhalb von WSL installieren. Kein sudo, kein pip und keine Python-Paketdownloads erforderlich. Der Installer lädt tgrep 1.0.5 und ripgrep 15.2.0 aus offiziellen Releases; SHA256-Werte stehen fest in dependencies.lock.json.

git clone https://github.com/Jeuners/tgrep-ai-skill.git
cd tgrep-ai-skill
./install.sh
export PATH="$HOME/.local/bin:$PATH"
local-search doctor

Der Installer richtet beide Skills ein:

• Claude Code: ~/.claude/skills/local-search/
• Codex: ~/.agents/skills/local-search/

Er installiert einen unabhängigen Laufzeitordner unter ~/.local/share/tgrep-ai-skill/. Der Checkout kann danach verschoben werden. Bestehende Konfiguration und Modellwahl bleiben erhalten; fremde gleichnamige Launcher oder Skills werden nicht überschrieben. Die Home-Wurzel wird registriert, aber noch nicht indexiert. Neue Agent-Sitzung öffnen, falls der Skill nicht erscheint.

Nur einen Agenten installieren:

./install.sh --target claude
./install.sh --target codex

Installation durch einen Agenten: Gib Claude Code oder Codex diesen Auftrag:

Installiere https://github.com/Jeuners/tgrep-ai-skill für Claude Code und Codex. Lies zuerst die README, führe den Installer aus und prüfe local-search doctor. Verwende mein vorhandenes Ollama-Modell. Starte noch keine Home-Indexierung.

Ollama und Qwen

Die direkte Suche funktioniert ohne LLM. Für ask muss Ollama separat installiert und gestartet sein:

ollama serve

Bei laufender Ollama-App ist kein zweiter Server nötig. In einem weiteren Terminal:

ollama list
# Nur falls das Modell fehlt: rund 6,6 GB Download
ollama pull qwen3.5:latest
local-search doctor

Dieses Modell aus der offiziellen Ollama-Library ist die Voreinstellung. Ein anderes installiertes Modell wählen, etwa eine kleinere Variante:

local-search model qwen3.5:4b

Modell und Loopback-URL stehen in ~/.config/local-search/config.json. Vor jeder Modellanfrage werden die Ollama-Metadaten geprüft: Cloud-Modelle, Remote-Aliasse und Modelle ohne erkennbare lokale Gewichte werden abgewiesen. Der Installer lädt weder Ollama noch Modellgewichte ungefragt herunter. Modellgewichte sind nicht Teil dieses MIT-Projekts; ihre eigenen Lizenzbedingungen gelten. Der Standardtag verweist auf die jeweils aktuelle Version und kann sich ändern. Ein Tag wie qwen3.5:4b legt die Modellgröße fest, bleibt aber ebenfalls veränderlich und garantiert keine unveränderten Modellgewichte.

Home und weitere Ordner

local-search preview home
local-search index home

local-search add projekte "/Volumes/Projekte"
local-search preview projekte
local-search index projekte

local-search add backend "$HOME/Desktop/backend" --exclude vendor --max-filesize 16M
local-search status

preview listet eine Dateianzahl, Beispiele und Ausschlüsse; die Zahl ist eine Schätzung vor Inhalts-/Binärprüfung. Bei gekappter Ausgabe ist sie eine Untergrenze. index baut synchron auf und startet danach einen Hintergrundserver. Es gibt keinen Login-Autostart; eine spätere Suche startet den Server bei Bedarf.

Standardausschlüsse: .git, node_modules, .venv, venv, target, dist, build, pycache, .ssh, .gnupg, .aws, .azure, .ollama, .Trash, Library, Caches. Ausschlüsse gelten als Verzeichnisnamen auf jeder Ebene. Standard-Dateigrößenlimit: 8 MiB. Normale Ignore-Regeln gelten auch außerhalb eines Git-Repositories. Symlinks werden nicht verfolgt.

Versteckte Nachkommen werden nicht indexiert: tgrep 1.0.5 unterstützt serve --hidden nicht. Einen versteckten Projektordner gegebenenfalls als eigene Wurzel registrieren. PDFs, Office, Bilder, Archive und semantische Embedding-Suche sind nicht enthalten. Ausschlüsse ersetzen keine allgemeine Geheimniserkennung.

Suchen

local-search search "WebSocket" --root projekte
local-search search 'auth|login' --regex --root backend
local-search ask "Wo wird die Anmeldung geprüft?" --root backend
local-search search "TODO" --root backend --root projekte
local-search search "Rechnungsnummer" --all --paths-only
local-search search "removed_function" --root backend --fresh

Ohne --root wird die spezifischste registrierte Wurzel um das aktuelle Arbeitsverzeichnis verwendet. --all durchsucht alle registrierten Wurzeln. Überlappende Treffer werden nach kanonischem Dateipfad und Zeilennummer dedupliziert; überlappende Indizes können trotzdem zusätzlichen Speicher und Sucharbeit kosten.

Ausgabe: JSON mit Treffern, Quellen, Backend, Aktualität, Warnungen und truncated. Standardmäßig höchstens 40 Treffer. --limit 100 erhöht das Limit. Jeder Report nennt zusätzlich match_count: die pro Wurzel und Suchanfrage gelieferten Treffer vor der globalen Zusammenführung. Diese Zahl ist bereits durch das jeweilige Suchlimit begrenzt; bei report.truncated können weitere, nicht gezählte Treffer existieren. Die Summe kann wegen der Deduplizierung größer als die zusammengeführte Trefferliste sein. Bei globaler Kappung die ausgewählten Wurzeln einzeln durchsuchen oder --limit erhöhen. Zeilentexte sind auf 2.000 Zeichen begrenzt; ask erhält höchstens rund 12.000 JSON-Zeichen Quellenkontext und führt maximal drei Suchbegriffe pro Wurzel aus.

Ein laufender Index ist eventuell konsistent. Während Aufbau oder erkennbar gestörter Aktualisierung wird frisch mit ripgrep gesucht. --fresh erzwingt das auch für wichtige Negativbefunde. Ein gleichzeitig verändertes Dateisystem ist kein atomarer Snapshot. ripgrep und tgrep können bei Randfällen ihrer Ignore-/Binärbehandlung abweichen.

Exitcodes: 0 Erfolg/Treffer, 1 keine Treffer, 2 Fehler, 130 abgebrochen. Ollama-Ausfall ist ein Fehler bei ask; search bleibt nutzbar.

In Claude Code: /local-search. In Codex: $local-search. Bei expliziten Vorgaben „immer zuerst rg“ muss die übergeordnete Regel eine Ausnahme erlauben; der Skill überschreibt sie nicht.

Datengrenze: tgrep und Qwen arbeiten lokal. Ausgaben, die ein Claude-/Codex-Agent liest, gelangen dennoch in dessen Kontext. --paths-only unterdrückt Ausschnitte und generierte Antworten, nicht Dateinamen. Bei ask --paths-only wird nur die Frage zur lokalen Suchplanung an Ollama geschickt.

Wartung

local-search stop home
local-search index home      # vollständiger Neuaufbau mit anschließendem Start
local-search remove backend # Registrierung entfernen, Index behalten

Konfiguration: ~/.config/local-search/config.json. Indizes/Status/Serverlogs: ~/.local/share/local-search/indexes/. XDG_CONFIG_HOME und XDG_DATA_HOME werden unterstützt. Eine geänderte Wurzelkonfiguration bekommt einen neuen Indexpfad. Vor manuellen Konfigurationsänderungen den Server stoppen; danach neu indexieren.

Update im Checkout:

git pull --ff-only
./install.sh

Für reproduzierbare Installation vorher einen Release-Tag auschecken. Updates legen einen neuen Laufzeitordner an; alte bleiben für laufende Server erhalten. Server stoppen und neu starten, damit sie die neue Binärdatei verwenden.

Deinstallation:

local-search stop home
# Weitere laufende Wurzeln ebenfalls stoppen.
./install.sh --uninstall

Entfernt den verwalteten Launcher und die Skills. Konfiguration, Indizes und alte Laufzeitordner bleiben absichtlich erhalten und können nach Prüfung manuell entfernt werden.

Fehlerbehebung und Entwicklung

• command not found: PATH setzen oder ~/.local/bin/local-search aufrufen.
• Python/venv fehlt: Python 3.10+ installieren; unter Debian/Ubuntu gegebenenfalls das passende python3-venv-Paket.
• Modell nicht erreichbar: ollama list, laufende App bzw. ollama serve prüfen.
• macOS-Zugriff verweigert: betreffende Ordner benötigen ggf. Zugriff für das verwendete Terminal. Nicht lesbare Pfade werden als Fehler gemeldet.
• Index hängt: local-search status und server.log im gemeldeten Indexpfad lesen.
• "PID identity changed": die Identität der vermerkten Prozess-ID stimmt nicht mehr mit dem gespeicherten Suchserver überein; deshalb wird kein Signal gesendet. Mit ps die gemeldete PID prüfen. Nur wenn die Zuordnung nachweislich veraltet ist und kein Suchserver mehr diesen Index verwendet, die gemeldete owner.json entfernen. Einen fremden Prozess dafür nicht beenden; anschließend erneut starten.
• Große Verzeichnisse: mit ausgewählten Projektwurzeln beginnen; Home verbraucht je nach Inhalt erheblich Plattenplatz. Der Server startet mit 512 MiB Indexaufbau-Budget und 25 % CPU-Budget; dies ist kein hartes Prozess-RAM-Limit.
• Offline: Releasearchive vorher herunterladen und ./install.sh --asset-cache /pfad/zu/archiven verwenden. Fehlende Archive werden weiterhin online angefordert. Abhängigkeiten werden stets per SHA256 geprüft.

PYTHONPATH=src python3 -m unittest discover -s tests -v

Integrationstests mit echten Binärdateien:

LOCAL_SEARCH_INTEGRATION=1 \
LOCAL_SEARCH_TGREP=/pfad/zu/tgrep \
LOCAL_SEARCH_RG=/pfad/zu/rg \
PYTHONPATH=src python3 -m unittest discover -s tests -v

Vollständige isolierte Installation inklusive Update und Deinstallation: python3 scripts/smoke_install.py. Optionaler Test des vorhandenen lokalen Modells mit ausschließlich synthetischem Quelltext: python3 scripts/smoke_ollama.py.

Herkunft und Lizenz

MIT, siehe LICENSE. Unabhängiges Integrationsprojekt, kein offizielles Microsoft-, Anthropic- oder OpenAI-Produkt.

Autorschaft: Implementierung geschrieben mit OpenAI Astra. Review und Überarbeitung durch Claude von Anthropic. AI Operator: H.G.O.D..

• Microsoft tgrep, MIT
• ripgrep, MIT oder Unlicense
• Ollama API
• Claude Code Skills

Die Installer-Downloads enthalten offizielle Binärdateien; Quellcode und Lizenztexte der Abhängigkeiten sind in deren verlinkten Repositories verfügbar.