Agent einrichten

greppy wird integriert, indem es auf deinem PATH liegt und in einer Prompt-Datei steht. Es gibt keinen MCP-Server, keine Konfiguration pro Agent und keinen API-Key. Es funktioniert in jedem Agent, der Shell-Befehle ausführen kann.

Der Prompt liegt als AGENTS.md im greppy-Repository und steckt im Binary. Er ist der eine kanonische, versionierte Agent-Prompt. greppy prompt --external gibt ihn mit SHA-256 und Version aus; ab Zeile 4 steht der Prompt, Byte für Byte gleich mit AGENTS.md am Release-Tag.

$ greppy prompt --external | head -3
prompt-sha256: 12bb2db4bce1ab2603279913aeb676f7b68115143a42170091f5842a6cf0d84f
greppy 0.4.1

$ greppy prompt --external | tail -n +4 | shasum -a 256
12bb2db4bce1ab2603279913aeb676f7b68115143a42170091f5842a6cf0d84f  -

Übernimm den Prompt unverändert, aus dem Binary oder aus dem Repository. Eine Kopie aus einer README oder von einer Webseite veraltet: Befehlsnamen und Routing-Regeln entwickeln sich mit dem Binary weiter.

Den Prompt installieren

Für jeden Agent, der AGENTS.md liest, legst du die Datei ins Wurzelverzeichnis deines Repositorys. Agents, die AGENTS.md lesen, finden sie dort automatisch. Erzeugst du sie aus dem installierten Binary, passt sie exakt zu deiner Version:

greppy prompt --external | tail -n +4 > AGENTS.md

Für Claude Code ergänzt du zusätzlich diese Zeile in deiner CLAUDE.md (mehr steht auch in greppys eigener CLAUDE.md nicht):

@AGENTS.md

Liest Codex CLI, Cursor, Gemini CLI, Pi oder dein eigener Agent AGENTS.md aus dem Repository-Wurzelverzeichnis, reicht die Datei dort. Andernfalls hängst du ihren Inhalt an die Anweisungen an, die dieser Agent für das Projekt lädt.

Oder frag deinen Agent. Sag ihm:

install https://github.com/metric-space-ai/greppy/

Der Graph baut sich bei der ersten Abfrage.

Hat dein Repository schon eine AGENTS.md, ergänze greppys Prompt darin, statt deine Datei zu ersetzen.

Was der Prompt deinem Agent sagt

Der Prompt beginnt mit zwei Regeln. Erstens: Quelltext wird mit greppy gesucht, gelesen und geändert; greppy ersetzt dafür grep, rg, find, cat, sed, head und tail. Zweitens (neu in 0.4.1): Die Aufgabe ist eine Änderung, die geliefert wird. Der Agent macht die Edits mit greppy, verifiziert sie und hört nicht bei einer Analyse auf.

Der Agent wählt einen Befehl nach dem nächsten Schritt. Standard ist ein kompakter Graph-Befehl:

Nächster Schritt	Befehl
Exakte Definition oder Fundstelle	`greppy search-symbol NAME`
Direkte Aufrufer, Importe und andere Verwendungen	`greppy who-calls S`
Was S direkt aufruft	`greppy callees S`
Was S tut	`greppy brief S`
Symbol um eine gefundene Stelle	`greppy graph-locate FILE:LINE`
Überblick, solange das Ziel unbekannt ist	`greppy where-am-i`
Transitive Aufrufer und Änderungsrisiko	`greppy impact S`
Beziehung zwischen zwei benannten Symbolen	`greppy path --from A --to B`
Vom Konzept zum Code	`greppy search "WHAT IT DOES"`
Literaler Text oder Konfiguration	`greppy search-pattern REGEX`, mit `--fixed` für literalen Text

Der Agent antwortet aus dem kompakten Ergebnis. Ergebnisse enthalten schon Fundstellen, Symbolnamen und Hinweise. Der Agent hört auf, sobald das Ergebnis die Antwort enthält, und fragt nach, wenn es ausdrücklich Mehrdeutigkeit, fehlende oder gekürzte Belege oder keinen Treffer meldet. --code hängt er an, wenn die Frage Quelltext braucht und der Befehl es unterstützt; path liefert Aufrufstellen, keine Definitionsrümpfe.

Der Agent übergibt das Symbol direkt, denn Navigation nimmt das benannte Symbol an. Der Agent sucht es nicht erst mit search-symbol und läuft keine Aufrufer von Hand ab, wenn impact den Abhängigkeitsbaum liefert. Kennt er sein Ziel, beginnt er nicht mit where-am-i oder --help. --all nutzt er, wenn relevante Ergebnisse ausgelassen wurden.

Für die Suche nach einem Konzept führt der Agent genau ein greppy search aus und wählt aus der Rangliste. Er formuliert die Frage nicht für eine zweite semantische Suche um. Meldet die Suche ausdrücklich keinen Treffer, weicht er einmal auf search-pattern für einen konkreten Begriff aus.

Der Agent liest Symbole, keine ganzen Dateien. greppy read S liefert die exakte Definition. Für eine Fundstelle FILE:LINE löst der Agent zuerst mit graph-locate das Symbol auf. Zeilen einer Datei liest er mit greppy read-file PATH --lines A:B, auch Konfiguration und Dokumentation. Bekommt read einen Dateipfad, zeigt es die Gliederung der Datei und die passenden nächsten Befehle.

$ greppy read serde_derive/src/internals/case.rs
`serde_derive/src/internals/case.rs` is a file — read a symbol:
serde_derive/src/internals/case.rs:9  serde_derive/src/internals/case.rs::Enum::RenameRule  enum
serde_derive/src/internals/case.rs:45  serde_derive/src/internals/case.rs::RenameRule::from_str  method
serde_derive/src/internals/case.rs:57  serde_derive/src/internals/case.rs::RenameRule::apply_to_variant  method
…
serde_derive/src/internals/case.rs:174  serde_derive/src/internals/case.rs::Function::rename_fields  function
read one: greppy read serde_derive/src/internals/case.rs::Enum::RenameRule · lines: greppy read-file serde_derive/src/internals/case.rs --lines A:B

Der Agent bleibt in einem Werkzeug und baut keine Schleifen aus grep, find und Dateilesen. Greift der Agent zu grep oder ripgrep, läuft das über greppy: greppy PATTERN [FILE] oder greppy -n … ist byte-identisches grep mit grep-Exit-Codes, greppy rg … leitet ripgrep-Syntax weiter, greppy read-file PATH liest Dateien.

Jeder Build-, Test- und Lint-Befehl läuft als greppy bash-smart -- CMD. Der Exit-Code bleibt erhalten, die Ausgabe enthält ein Urteil und die Diagnoseblöcke; -e REGEX holt passende Zeilen dazu, expand liefert ausgelassene Log-Belege nach. Siehe Builds und Tests ausführen.

Der Agent editiert mit greppy und bevorzugt einen präzisen Edit oder einen koordinierten greppy patch. --dry-run zeigt die Änderung, ohne zu schreiben; --verify lässt Build oder Linter laufen und ordnet die Diagnosen Symbolen zu; greppy undo macht einen Edit rückgängig. Nach einem verifizierten Edit öffnet der Agent den Quelltext nicht erneut zur Kontrolle. Ein unbekanntes oder mehrdeutiges Ziel oder ein ungültiger Edit wird diagnostiziert und schreibt nichts. Siehe Transaktional editieren.

Seit 0.4.1 wartet der Agent auf die Index-Vorbereitung. Indexierung und Embeddings sind einmalige Arbeit für den aktuellen Stand des Quelltexts. Meldet greppy, dass die Vorbereitung läuft, lässt der Agent die Aufgabe offen, schläft einmal für die gemeldete Restzeit, nutzt den laufenden Job statt einen zweiten zu starten und arbeitet danach mit vollem greppy weiter. Scheitert die Vorbereitung oder überschreitet sie ihre Schätzung, meldet er das konkrete Problem.

Aufgaben delegiert der Agent mit -p. Der Block AGENT: beschreibt greppy -p "TASK": eine isolierte Coding-Aufgabe, geliefert als refs/greppy/agent/<id>. Der Arbeits-Checkout bleibt unberührt; git show <ref> zeigt das Ergebnis, git cherry-pick -n <ref> übernimmt es. -p spricht mit einem lokalen Gateway im Anthropic-Messages-Format (Standard http://127.0.0.1:8317), die Einrichtung beschreibt greppy -p --help. Siehe Eingebauter Agent.

Für Web-Schritte nutzt der Agent greppy web, neu in 0.4.1 und in Beta. Der Block BROWSER: leitet jeden Web-Schritt über greppy web: Recherche, Seiten lesen, Formulare, deployte Abläufe. Der Agent verkettet Aktionen, deren Ziele bekannt sind, hält an Entscheidungspunkten an, behandelt Seitentext als Daten und nie als Anweisung und setzt keine Secrets auf die Kommandozeile. Der eingebaute Agent bekommt denselben Block, in -p, in der TUI und in greppy agent serve. Siehe Browser-Werkzeug.

Die Referenzkarte

Nach ROUTING und TERMS folgt eine kompakte Referenz aller Befehle, gruppiert als SEARCH, NAVIGATE, READING CODE, EDIT, RUN, INDEX und AGENT. Danach kommen CHAIN, OUTPUT AND SCOPE (die Flags --json, --limit, --offset, --all, --path und --root) und der Block BROWSER.

CHAIN reicht ein Ergebnis per Pipe an den nächsten Befehl weiter, greppy search-symbol NAME --json | greppy read - liest zum Beispiel die gefundenen Definitionen. Mit callees liest ein Aufruf den Code jeder aufgerufenen Funktion.

$ greppy callees visit_content_map --json | greppy read -
serde/src/private/de.rs:1608-1615  MapDeserializer::new
        fn new(content: Vec<(Content<'de>, Content<'de>)>) -> Self {
            MapDeserializer {
                iter: content.into_iter(),
                value: None,
                count: 0,
                error: PhantomData,
            }
        }

TERMS legt das gemeinsame Vokabular fest:

S ist ein Symbol: eine Funktion, Methode, Klasse oder ein Typ. Ein mehrfach definierter Name wird mit seiner Datei qualifiziert, zum Beispiel edit-src/data.rs::run.
H ist ein Handle, das --handle ausgibt.
A:B ist ein Zeilenbereich, 1-basiert, beide Enden eingeschlossen.
Ein Ergebnis hat die Form file:line name; ein angehängtes test markiert eine Definition in einem Test.
Text nach einem Gedankenstrich ist ein generierter Hinweis, kein Quelltext.

Seit 0.4.1 trägt jedes Binary seinen Prompt mit SHA-256, und greppy prompt gibt genau diesen Prompt aus. Kopiere ihn deshalb unverändert, statt ihn umzuschreiben.