Eingebauter Agent

greppy ist ein reiner Coding-Agent. Jede Aufgabe läuft in einem eigenen, temporären Copy-on-Write-Worktree und endet immer als Pull Request: ein Proposal-Commit auf refs/greppy/agent/<run-id>. Sobald der Proposal gespeichert ist, entfernt greppy den Worktree wieder. Dein Checkout, sein HEAD und sein Git-Index bleiben unverändert.

Du startest den Agenten direkt aus der Shell oder lässt ihn als Subagent von einem anderen Agenten arbeiten, einmalig per greppy -p oder ferngesteuert über greppy agent serve.

So läuft eine Aufgabe

Die Commit-Message ist die finale Antwort des Agenten, die Beschreibung des Pull Requests: ein einzeiliger Titel, Status: (done, partial oder blocked), was sich geändert hat und warum (mit file:line), wie es verifiziert wurde und was offen ist. Eine explizite Title:-Zeile wird zum Betreff, sonst die Zeile vor Status:; die Antwort ist der Body.

Den Worktree behältst du nur mit --keep-worktree. Endet ein Lauf mit einem Fehler, bevor ein Proposal existiert, bleibt der Worktree 24 Stunden für die Fehlersuche erhalten. Erreicht ein Lauf ein Limit (Exit 5), ist der Proposal trotzdem gespeichert und der Worktree entfernt.

Voraussetzung: ein lokales Modell-Gateway

greppy bringt kein Chat-Modell mit. Der Agent spricht die Anthropic Messages API über einfaches HTTP mit einem lokalen, Anthropic-kompatiblen Gateway. Das Standard-Gateway ist CLIProxyAPI; es übersetzt die gängigen Chat-Formate und Provider in dieses Wire-Format.

export GREPPY_ENDPOINT=http://127.0.0.1:8317   # der Default; oder --endpoint URL
export GREPPY_MODEL=MODEL                      # eine Modell-ID, die dein Gateway anbietet; oder --model
export GREPPY_API_KEY=YOUR_GATEWAY_KEY         # nur wenn das Gateway einen Key verlangt

Der Client hat keinen TLS-Stack, er erreicht also Plain-HTTP-Endpoints wie ein Gateway auf localhost. Die Modell-ID geht unverändert ans Gateway. Den Key sendet greppy als x-api-key und als Authorization: Bearer. Ein Key-Flag gibt es bewusst nicht: Keys gehören nicht auf die Kommandozeile. greppy -p --help beschreibt das komplette Setup.

Einmalig: greppy -p

greppy -p "add tests for clamp_value" --model MODEL
greppy -p "keep going" --continue

greppy -p "TASK" ist der Headless-Modus für Skripte und für Aufgaben, die ein anderer Agent abgibt. In der ersten Zeile auf stderr steht session: <session_id>.

Usage:
  greppy agent ["INITIAL TASK"]
  greppy agent stdio [--model M] [--endpoint URL]
  greppy -p "TASK" [--model M] [--endpoint URL] [--max-turns N]
                   [--deadline-secs N] [--apply] [--diff] [--keep-worktree]
                   [--no-sandbox] [--skip-selfcheck]
                   [--continue | --resume ID] [--json]
  greppy -p --help

Es gibt keine festen Limits: keine Default-Grenze für Turns und keine festen Tool-Timeouts. Die Deadline des Laufs begrenzt beides. Große Tool-Ausgaben faltet greppy hinter expand agent-output-ID, statt sie abzuschneiden.

Ein führendes -p ist für den Agenten reserviert. Um mit grep nach dem Muster -p zu suchen, nutze greppy -e -p ….

Als Subagent

Ein anderer Agent übergibt greppy eine abgeschlossene Aufgabe mit greppy -p und bekommt den Pull Request zurück. Der Prompt im Modus -p sagt dem Agenten: Eine Person, ein Skript oder ein anderer Agent liest nur die finale Antwort und den Pull Request; Rückfragen beantwortet niemand, also entscheidet er Details selbst und benennt sie.

Externe Agenten finden die Anleitung dafür in der AGENTS.md, die greppy mitliefert.

AGENT:
  greppy -p "TASK" [--model M]       isolated coding task, delivered as refs/greppy/agent/<id>

The task does not edit the working checkout. Review with git show <ref>, apply with
git cherry-pick -n <ref>. greppy -p --help describes gateway setup.

Für längere Zusammenarbeit hostest du eine Session mit greppy agent serve und steuerst sie fern, siehe Fernsteuerung.

Den Pull Request prüfen und anwenden

git show refs/greppy/agent/<run-id>
greppy agent apply refs/greppy/agent/<run-id>

Der Proposal ist gegen eine erfasste Baseline gebaut: den gepinnten Commit plus deine sichtbaren gestagten, ungestagten und untracked Änderungen. greppy agent apply REF prüft genau diese Baseline, wendet nur die Änderungen des Agenten an und lässt deinen Git-Index byte-identisch. --apply bei greppy -p macht dasselbe am Ende des Laufs. Für Proposals auf uncommitteter Arbeit ist greppy agent apply der Weg. Externe Agenten, die nur Git haben, nutzen git cherry-pick -n REF, wie die AGENTS.md es beschreibt.

greppy agent apply mit einer Ref, die es nicht gibt, endet mit Exit 64.

Interaktiv: greppy agent

greppy agent
greppy agent "TASK" --model MODEL
greppy agent --continue

greppy agent öffnet eine Vollbild-Terminal-UI mit demselben Worktree, derselben Sandbox und demselben Proposal wie greppy -p. Das Transcript behält den Kontext über mehrere Prompts und zeigt gestreamte Antworten, Tool-Aktivität und Token-Verbrauch. /setup konfiguriert Gateway, Modell und die übrigen Einstellungen und speichert sie.

Sessions

Sessions liegen als Append-only-JSONL unter dem greppy-Datenverzeichnis (agent-sessions/<project>/<id>.jsonl; unter macOS ist das ~/Library/Application Support/greppy). Ein abgeschnittenes Ende stellt greppy bis zum letzten gültigen Eintrag wieder her. Secrets und Authorization-Header werden in Anzeige und Datei geschwärzt. Jede Session hat ein kopierbares Handle, greppy://sessions/<id>, das überall funktioniert, wo eine Session-ID erwartet wird.

greppy agent sessions list [--json] [--all-projects]
greppy agent sessions show ID [--json] [--full]
greppy agent sessions tail ID [--json] [--follow] [--lines N]
greppy agent sessions path ID

tail zeigt ohne --lines die letzten 40 Zeilen, --follow pollt bis SIGINT. Diese Befehle schreiben nie in den Store. IDs dürfen eindeutige Präfixe sein; eine unbekannte oder mehrdeutige ID endet mit Exit 2.

$ greppy agent sessions list
no sessions for project serde
$ greppy agent sessions show nope
no session nope in project serde

Der zweite Befehl endet mit Exit 2.

JSON-Events

greppy -p --json streamt ein JSON-Event pro Zeile auf stdout: session, text, tool_start, tool_finish, turn_complete, error und result. result ist immer die letzte Zeile. Menschenlesbare Diagnosen bleiben auf stderr.

Das erste SIGINT oder SIGTERM bricht an der nächsten sicheren Grenze ab und liefert trotzdem result mit status: "cancelled" und exit_code: 130. Ein zweites Signal beendet sofort.

Fernsteuerung

greppy agent serve [TASK] hostet eine Headless-Session auf einem Unix-Socket pro Benutzer. Ein optionaler TASK wird nach dem Setup als erste Aufgabe eingereiht. Jede Nachricht setzt dieselbe Aufgabe im selben Worktree fort; der steuernde Agent darf Folgeaufträge schicken oder einen Turn unterbrechen.

greppy agent sessions list --json meldet für jede Session den socket-Pfad. Eine andere Shell oder ein anderer Agent steuert die Session dann so:

greppy agent serve --model MODEL
greppy agent status    ID [--json]
greppy agent send      ID TEXT [--wait] [--json] [--source LABEL]
greppy agent attach    ID [--json] [--since-start]
greppy agent interrupt ID [--json]
greppy agent quit      ID [--json]

ID ist eine Session-ID, ein eindeutiges Präfix oder das Handle greppy://sessions/<id>.

Eine Session ohne lebenden Socket endet mit Exit 3 und nennt den Befehl greppy agent serve --resume ID, der sie neu startet.

ACP-Hosts: greppy agent stdio

greppy agent stdio --endpoint http://127.0.0.1:8317 --model MODEL

greppy agent stdio spricht das Agent Client Protocol (JSON-RPC, eine Nachricht pro Zeile) auf stdin und stdout für eine Host-Anwendung; Diagnosen gehen auf stderr. Der Host liefert den Arbeitsordner, wenn er eine Session anlegt oder lädt, und jeder Tool-Aufruf wartet auf die Freigabe des Clients. In diesem Modus editiert der Agent den Ordner des Clients direkt: Er legt keinen Worktree an und erzeugt keinen Proposal unter refs/greppy/agent/. Sein Prompt verspricht deshalb weder Worktree noch Pull Request. Sessions nutzen denselben Store wie greppy -p und greppy agent.

Speak the Agent Client Protocol on stdin/stdout.

Usage: greppy agent stdio [OPTIONS]

Options:
      --model <MODEL>        Initial model id. `session/set_model` can replace it [env: GREPPY_MODEL=]
      --endpoint <ENDPOINT>  Anthropic-Messages gateway base URL [env: GREPPY_ENDPOINT=] [default: http://127.0.0.1:8317]
      --max-turns <N>        Maximum assistant turns for one prompt [default: 0]
  -h, --help                 Print help

--max-turns 0, der Default, heißt: keine Grenze. Den Gateway-Key liest der Agent-Prozess aus GREPPY_API_KEY; ACP-Clients senden ihn nicht. Unterstützte Operationen stehen in docs/acp.md.

Ein Prompt, vier Modi

Alle Modi rendern ihren System-Prompt aus derselben Quelle. greppy prompt --mode one-shot|interactive|serve|acp|external druckt die jeweilige Fassung, mit --json samt SHA-256.

$ greppy prompt --mode one-shot | head -2
prompt-sha256: 12bb2db4bce1ab2603279913aeb676f7b68115143a42170091f5842a6cf0d84f
You are greppy, a coding agent. You never work in the user's checkout: every task runs in its own temporary worktree and ends as a pull request.

Die Fassungen unterscheiden sich in einer Zeile zur Rolle: Bei -p liest jemand nur Antwort und Pull Request, bei serve steuert ein anderer Agent, in der Terminal-UI kann eine Person Rückfragen beantworten.

Worktree und Sandbox

greppy legt den isolierten Worktree an, bevor das Modell die erste Anfrage bekommt. Ignorierte Dateien und Build-Caches werden nicht erfasst. Der Worktree hat einen privaten Git-Zustand: Er liest die Objekte des Basis-Commits nur lesend, sein Index, seine Refs, neue Objekte und Commits bleiben privat, bis der geprüfte Proposal importiert ist.

Ein Dateisystem-Adapter für Copy-on-Write (unter macOS FSKit) beschleunigt das Anlegen, wenn er aktiv ist. Ohne ihn nutzt der Agent gewöhnliche private Verzeichnisse mit demselben Proposal- und Apply-Ablauf.

greppy workspace setup            # optional: den Adapter der Plattform installieren und aktivieren
greppy workspace doctor --json    # optional: ihn prüfen
greppy index --agent-worktree     # optional: Worktree und Base des Agenten vorab aufwärmen

Tool-Prozesse dürfen nur in den Worktree schreiben, in ein Scratch-Verzeichnis pro Lauf (TMPDIR), in den greppy-Store des Worktrees und in ~/.cargo/{registry,git}. Lesen und Netzwerk bleiben offen. Die Beschränkung setzt unter macOS Seatbelt und unter Linux Landlock um. Credential-Umgebungsvariablen werden aus Tool-Prozessen entfernt, und Agent-Läufe verschachteln sich nicht. --no-sandbox oder GREPPY_NO_SANDBOX=1 schaltet die Beschränkung ab.

Repositorys mit Submodulen, Repositorys mitten in einem Merge, Rebase, Cherry-Pick, Revert oder Bisect und Repositorys mit Checkout-Filtern wie Git LFS weist der Agent ab, bevor das Modell startet (Exit 2).

Exit-Codes

Upgrade von v0.3.3

v0.3.3 kennt nur das einmalige greppy -p. Terminal-UI, Sessions, --continue, --resume, --json, greppy agent apply, agent serve, Fernsteuerung und agent stdio kommen mit 0.4.1. Die Flags --workspace-backend und --fresh aus v0.3.3 gibt es in 0.4.1 nicht mehr.