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: mehrere GB Download
ollama pull srchmnmichael/qwen3.5-9B-uncensored:latest
local-search doctor

Dieses Modell ist die Voreinstellung. Ein anderes installiertes Modell wählen:

local-search model qwen3.5:latest

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 ist ein Community-Modell und kann sich ändern.

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. 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.
• 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.

• 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.