Aufgaben abgeben, Commits zurückbekommen

Was du davon hast

Dein Hauptagent plant und verteilt, greppy setzt um. greppy -p "AUFGABE" startet einen Coding-Agenten, der in seiner eigenen Kopie deines Repositorys arbeitet und mit einem Commit endet: dem Pull Request. Dein Checkout bleibt unberührt, deine offenen Änderungen auch. Mehrere Aufgaben laufen parallel, jede in ihrem eigenen Worktree. Du prüfst jeden Commit und übernimmst, was passt.

So läuft eine Aufgabe ab

1. greppy legt einen temporären Copy-on-Write-Worktree an: den aktuellen Commit plus deine offenen Änderungen, staged, unstaged und untracked. Ignorierte Dateien wie node_modules oder target bleiben draußen. Ein geteilter Index deckt den unveränderten Code ab und folgt den Änderungen des Agenten.
2. Der Agent hat ein Werkzeug: greppy. Er navigiert über den Graph, liest Definitionen, ändert Symbole und lässt Build und Tests als bash-smart -- CMD laufen. Schreiben darf er in seinem Worktree. Lesen und Netz bleiben offen.
3. Der Agent arbeitet, bis die Aufgabe erledigt ist. Es gibt kein festes Rundenlimit. --max-turns N setzt auf Wunsch eines, danach folgt eine Berichtsrunde ohne Werkzeuge. Werkzeuge haben keine festen Timeouts, --deadline-secs N begrenzt den ganzen Lauf.
4. Die Änderungen im Worktree werden ein Commit auf refs/greppy/agent/<run-id>, der Pull Request. Sein Elternteil ist dein Ausgangsstand samt offener Änderungen, der Commit enthält also genau die Arbeit des Agenten. Die Commit-Nachricht ist seine Schlussantwort: Titel, Status: (done, partial oder blocked), was sich geändert hat, wie es geprüft wurde, was offen ist.
5. Ist der Pull Request gespeichert, löscht greppy den Worktree. Das gilt auch, wenn die Deadline den Lauf beendet: Exit 5, der Pull Request ist trotzdem da. Mit --keep-worktree bleibt der Worktree stehen; nach einem Fehler ohne Pull Request hält greppy ihn 24 Stunden bereit.
6. git show REF zeigt den Commit, greppy agent apply REF übernimmt genau die Änderungen des Agenten. Dein Git-Index bleibt dabei byte-genau gleich.

Ein Abnahmetest prüft diesen Ablauf mit echten Läufen: 13 von 13 Klauseln bestanden.

So funktioniert es

Aufruf durch den Hauptagenten

Dein Hauptagent startet die Aufgabe in seiner Shell, wartet auf das Ende und liest das Ergebnis:

greppy -p "Behebe den Fehler in clamp: Werte über dem Bereich sollen die Obergrenze liefern. Ergänze einen Test." \
  --deadline-secs 1800 --json > run.jsonl
tail -n 1 run.jsonl                             # das result-Event: status, exit_code, proposal_ref
git show refs/greppy/agent/<run-id>             # den Pull Request prüfen
greppy agent apply refs/greppy/agent/<run-id>   # übernehmen

Mit --json schreibt greppy ein JSON-Event pro Zeile auf stdout: session, text, tool_start, tool_finish, turn_complete, error und als letzte Zeile result. Das result-Event trägt status, exit_code und proposal_ref, dein Hauptagent weiß damit, wo der Pull Request liegt. Ein abgebrochener Lauf endet ebenso mit einem result-Event, Exit 130. Mit --continue oder --resume ID setzt eine Folgeaufgabe die Session fort.

$ greppy -p --help
…
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

Flags:
…
  --max-turns N       Optional cap on action turns, followed by one tool-free
                      report turn (unlimited by default)
  --deadline-secs N   Wall-clock budget in seconds (env GREPPY_DEADLINE_SECS);
                      the loop stops between turns; tool calls already issued
                      run for at most 30 s past the deadline
…
  --json              Stream newline-delimited JSON events on stdout (`greppy -p` only)
…
Exit codes:
  0  ok (clean, proposal saved, or applied)
  2  no gateway / bad usage / missing model / unsupported repository
  3  agent or loop error (unsaved workspace retained for up to 24 hours)
  4  --apply refused (dirty target) or cherry-pick conflict (ref still available)
  5  incomplete (explicit turn limit or deadline reached; proposal saved)

Was der Subagent mitbekommt

Jeder Modus hat seinen eigenen Systemprompt. greppy prompt --mode one-shot gibt den für -p exakt aus, mit --json samt SHA-256 dieser Fassung. Er sagt dem Agenten, dass sein Ergebnis ein Pull Request ist und dass niemand Rückfragen beantwortet.

$ greppy prompt --mode one-shot
…
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.
…
DONE means the pull request can be merged as it is: the task is fully implemented, the relevant tests pass, new behaviour has a test, and the diff contains nothing else (smallest change, in the style of the surrounding code). Do not stop at an analysis. If you are blocked, name the missing dependency; never claim a result you have not seen.

FINAL ANSWER is the pull request's description: a one-line title; Status: done, partial or blocked; what changed and why (file:line); how it was verified (commands and results); what is open.

-p: a person, a script or another agent reads only your final answer and the pull request; nobody can answer questions, so decide details yourself and name them.
…

Fernsteuerung

greppy agent serve hält eine Session headless auf einem Unix-Socket. Andere Shells und andere Agenten steuern sie über ihre Session-ID oder ein eindeutiges Präfix:

greppy agent serve --model MODEL
greppy agent send ID "Ergänze einen Test für leere Bereiche" --wait --json
greppy agent attach ID --json      # Events live mitlesen
greppy agent interrupt ID          # die laufende Runde abbrechen
greppy agent quit ID               # die Session beenden

Der Steuer-Socket gehört deinem Benutzerkonto: Jeder Prozess unter deinem Konto kann die Session steuern, auch andere Agenten. greppy agent öffnet denselben Agenten als Terminal-Oberfläche, mit demselben Ablauf aus Worktree, Sandbox und Pull Request.

Das Modell kommt über dein Gateway

Du wählst das Modell. greppy spricht die Anthropic-Messages-API mit einem lokalen Gateway, Standard ist http://127.0.0.1:8317. CLIProxyAPI ist der Standard dafür und übersetzt die großen Anbieter. Die Modell-ID geht unverändert durch, der Key steht in einer Umgebungsvariable und nie auf der Kommandozeile.

export GREPPY_ENDPOINT=http://127.0.0.1:8317   # Standard
export GREPPY_MODEL=MODEL                      # eine Modell-ID, die dein Gateway anbietet
export GREPPY_API_KEY=…                        # wenn dein Gateway einen Key verlangt

Die Befehle

Mehr in der Doku

• Eingebauter Agent: alle Flags, Sessions, JSON-Events, Fernsteuerung und Exit-Codes
• Worktrees und geteilter Index: wie Git-Worktrees und Agenten einen Index teilen
• Agent einrichten: greppy in Claude Code, Codex, Gemini CLI, pi und OpenCode