pi /until-done im Praxiseinsatz: der Agent arbeitet, bis der Beweis steht

Das Grundproblem jedes autonomen Coding-Agents ist nicht mangelnde Geschwindigkeit, sondern mangelnde Ehrlichkeit: Der Agent meldet „fertig“, sobald er glaubt, fertig zu sein. Tests, die noch rot sind, werden dabei gern übersehen. /until-done für den pi Coding Agent dreht das Vertrauensmodell um: Das Ende eines Auftrags entscheidet nicht das Modell, sondern ein vorher definierter, maschinell prüfbarer Beweis – und selbst den prüft ein zweites LLM, der „Judge“, bevor das Ziel als erledigt gilt.

Das Konzept ist als „Ralph-Loop“ bekannt (Hermes Agents /goal, der Ralph-Loop in Codex CLI). pi-until-done ist die native Pi-Implementierung: eine Extension, die aus einer Absicht einen festgeschriebenen Vertrag („North Star“), einen Abhängigkeitsplan und einen begrenzten Autonomie-Loop macht. Dieser Artikel zeigt die Installation, einen kompletten Durchlauf und die Kommandos, die man im Alltag braucht.

Installation und Voraussetzungen

pi install npm:pi-until-done

Alternativ funktionieren auch Git- und lokale Quelle (pi install github:srinitude/pi-until-done, pi -e /pfad/zu/pi-until-done/extensions/until-done.ts). Danach lädt Pi die Extension beim nächsten Start; mit Ctrl+O oder pi list kontrolliert man, dass sie aktiv ist.

Drei Voraussetzungen solltet ihr vorher prüfen:

Voraussetzung	Warum
Pi-Version im Lockstep	Die Extension pinnt auf genau eine Pi-Release – Stand 0.3.1 (Juli 2026): @earendil-works/pi-*@0.81.1. Trotzdem haben wir sie auf der aktuellen Pi 1.0.2 installiert und geladen: fehlerfrei, der --until-done-Flag-Pfad feuert (identisches Verhalten auf 0.99.2). Offiziell CI-getestet ist aber nur 0.81.1 – nach einem pi update --self daher pi update --extensions prüfen, ob es eine passende Neu-Release gibt.
Node >=22.19	Laufzeit-Anforderung der Extension. Die gebündelte Pi-Installation bringt Node 22.23.1 mit, das ist erfüllt.
mise auf dem PATH	Verifikationsbefehle laufen über mise exec --; ein Befehl, der schon mit mise run/mise exec beginnt, bleibt unverändert.

Getestet (Oktober 2026): pi install npm:pi-until-done lief auf Pi 1.0.2 (und zum Vergleich 0.99.2) durch. Die Extension lud in mehreren Sessions fehlerfrei – auch parallel zu anderen installierten Paketen – und der --until-done-Flag-Pfad erreichte die Setup-Logik. Der dokumentierte volle Loop inklusive Judge-Roundtrip ist offiziell nur gegen 0.81.1 CI-getestet – wer auf einer neueren Pi produktiv lange Läufe fährt, sollte einmal einen kompletten Zyklus mit dem geplanten Zielmodell durchziehen, bevor er sich darauf verlässt.

Der erste Durchlauf

Ein Auftrag beginnt mit einer Absicht – am besten eine, die man in einen verifizierbaren Endzustand übersetzen kann:

/until-done finish migrating the auth test suite from Jest to Vitest

Pi durchläuft dann einen festen Ablauf:

1. Klären – Outcome, Goal-Typ (ticket vs. exploratory), erreichbare Evidenzflächen (Logs, Tests, Builds) und der verifyCommand.
2. Vertrag anzeigen – Goal, „Done when“-Kriterien, verifyCommand, askBefore-Grenzen werden als Kontrakt präsentiert.
3. Approve – ihr bestätigt mit /until-done approve; erst jetzt wird der North Star per until_done_set gesperrt. Die fünf Felder Goal, Done-Kriterien, verifyCommand, askBefore und Judge-Modus sind danach für die Laufzeit des Ziels unveränderlich.
4. Arbeiten – Pi arbeitet die Phasen ab: ANALYSIS → BOOTSTRAP → RED → GREEN → REFACTOR → VERIFY → DONE. Für Code-Ziele gilt TDD-first: Vor jedem Code-Change kommt eine rote Testaufgabe (RED), am Ende steht die Verifikation.
5. Weiterlaufen – Nach jeder Runde agent_settled setzt die Extension selbstständig fort, solange das Ziel aktiv ist. Ein versteckter Chat-Eintrag nach Kompaktion (re-anchor) hält den Loop auch nach session_compact am Laufen.
6. Beweisen – Wenn alle Tasks done sind, ruft Pi until_done_complete mit dem wörtlichen Output des verifyCommand als Evidence auf.
7. Richten – Der Judge prüft Goal, Kriterien und zitierte Evidenz und gibt { "verdict": "done" | "continue" } zurück. Nur ein done-Urteil schließt das Ziel ab. Exports landen in .until-done/tasks.yaml und .until-done/distilled.md.

Ein realistischer Vertrag für das Beispiel oben sähe so aus:

goal: Auth-Testsuite von Jest auf Vitest migrieren
doneCriteria:
  - "alle Tests in packages/auth laufen unter vitest grün"
  - "keine jest-Referenzen mehr in packages/auth"
verifyCommand: pnpm vitest run packages/auth
askBefore: ["git push", "git commit -m 'migrate auth to vitest'"]
judgeModel: { provider: "anthropic", modelId: "claude-sonnet-4-5" }

Der Judge: Warum ein zweites Modell

Der häufigste Ausfall des Ralph-Loops ist die Selbstbewertung: Ein Modell, das seine eigene Arbeit bewertet, redet sich gern zu früh „fertig“. Pi-until-done verlangt deshalb immer einen Judge – es gibt keinen lautlosen Weg daran vorbei:

• Cross-Model (empfohlen): ein Modell anderes als das arbeitende, z. B. Sonnet als Executor und Opus als Judge. Der Judge sieht nur Goal, Kriterien, verifyCommand und die zitierte Evidenz – keine Executor-Geschichte, keine Voreingenommenheit.
• Same-Model: sameModelJudge: true – bewusst schwächer, nur wenn kein zweites Modell verfügbar ist.
• Der Judge liefert striktes JSON; ein continue-Urteil blockiert den Abschluss und begründet die Lücke.

Als Session-Default konfiguriert man den Mode einmal:

/until-done judge anthropic/claude-sonnet-4-5
/until-done judge same
/until-done judge clear

Wichtig: Der Judge erhält die Completion-Evidenz. Keine Secrets in Goal, Evidence, Task-Notizen oder Exports packen.

Kommandoreferenz

Kommando	Zweck
/until-done <Absicht>	Neuen Ziel-Vertrag + Plan entwerfen und anzeigen
/until-done approve	Approval-Dialog für den sichtbaren Entwurf öffnen
/until-done status	Einzeiler zum aktuellen Zustand
/until-done detail	Voller Vertrag + Zustand
/until-done tasks	Aktueller Plan (YAML)
/until-done plan	Pfad zu .until-done/tasks.yaml
/until-done pause / resume	Loop anhalten (Ziel bleibt) / fortsetzen (re-armed)
/until-done cancel	Ziel endgültig löschen (einziger Weg, den North Star zu ändern)
/until-done budget N	Turn-Budget setzen (Default 20, Dialog ab 500)
/until-done autopilot	Setup-Dialog für die Session überspringen
/until-done judge …	Judge-Default anzeigen/setzen/leeren
/until-done ask <Frage>	Neben-Frage stellen, ohne den Loop zu unterbrechen
/until-done northstar	Gesperrte Vertragsfelder anzeigen
/until-done replan-log	Alle Planrevisionen mit Begründung
/until-done help	Eingebaute Hilfe

Praxistipps

• Falsifizierbare Done-Kriterien. „Tests grün“ plus „keine X mehr“ schlägt „sauber refaktorieren“. Der Judge kann wörtliche Befunde prüfen, keine Stimmungen.
• Der verifyCommand ist das Gesetz. Nicht „Tests passen“, sondern pnpm vitest run … mit Output zitieren. Der Judge lehnt Paraphrasen ab – ein judge_rejected mit gleicher Evidenz erneut zu versuchen, ist sinnlos.
• Budgets setzen. /until-done budget 30 nach Bedarf. Der Loop hat mehrere Bremsen: Turn-Budget, Spin-Guard auf wiederholte identische Fehler, User-Interjektion und einen „Clean-End“-Nudge, wenn alle Tasks done sind, aber complete aussteht. Nach zwei solcher Nudges pausiert der Loop und wartet auf euch.
• Nebenarbeit über ask. /until-done ask Ist der NPM-Token schon hinterlegt? beantwortet Zwischenfragen, ohne den Goal-State zu berühren.
• Replan statt raten. Taucht neue Arbeit auf, ruft Pi until_done_replan mit Begründung (residual_work_discovered) – nicht still weitererfinden.

Wann ihr es nicht benutzen solltet

• One-Shot-Aufgaben. Eine Einzeländerung oder eine Frage braucht keinen Loop und keinen Judge – jede Runde kostet mindestens einen zusätzlichen Judge-Call.
• Offene Ziele ohne prüfbaren Endzustand. „Mach den User glücklich“ und „recherchiere XYZ“ lassen sich an keinem falsifizierbaren Kriterium messen. Für Dokumentations-/Recherche-Ziele den Goal-Typ exploratory/none nutzen – oder klassisch interaktiv arbeiten.
• Wenn kein zweites Modell verfügbar ist und Same-Model-Selbstbewertung zu schwach erscheint. Der Judge ist der Kern des ehrlichen Abschlusses.

Einordnung

/until-done ist Teil einer ganzen Familie von Loop-Werkzeugen. untilgreen setzt als Gegenentwurf auf deterministische Shell-Gates statt auf LLM-Unterschrift, loop-until (Codex), do-until/cc-until-done (Claude Code) und die Goal-Extensions (@narumitw/pi-goal, pi-goal-x) decken ähnliche Muster ab. Wer weiterlesen will, findet in der Pi-Addon-Übersicht die Einordnung der Loop-Kategorie im Gesamt-Ökosystem – inklusive Alternativen wie untilgreen, bei denen nicht ein Modell, sondern ein Exit-Code über „fertig“ entscheidet.

Der Mehrwert von /until-done ist die Beweispflicht: Der Agent darf nicht aussteigen, bevor ein zweites Modell den wörtlichen Output des Verifikationsbefehls gegengezeichnet hat. Wer lange autonome Läufe fährt, gewinnt damit genau die Eigenschaft, die Coding-Agenten am häufigsten fehlt – einen nachvollziehbaren, abgesicherten Abschluss. Klein anfangen: ein Ziel, ein verifyCommand, ein Budget, und nach dem ersten grünen Urteil wirkt die Selbstüberschätzung des Agents plötzlich sehr viel kleiner.