Pi Agent Harness: ein TypeScript-Monorepo für Coding-Agenten

Pi als Agent-Harness: die fünf Pakete im Monorepo

Das Repository von earendil-works versteht sich als Heimat des Pi-Agent-Harness-Projekts, in dessen Zentrum ein selbst erweiterbarer Coding-Agent steht. Die Struktur fällt in fünf npm-Pakete: @earendil-works/pi-ai bietet eine einheitliche LLM-API über mehrere Anbieter hinweg, namentlich OpenAI, Anthropic und Google. @earendil-works/pi-agent-core stellt die Agenten-Laufzeit mit Tool-Aufrufen und Zustandsverwaltung. @earendil-works/pi-coding-agent liefert die interaktive Coding-Agent-CLI.

Dazu kommen zwei Stützpakete: @earendil-works/pi-tui, eine Terminal-UI-Bibliothek mit differenziellem Rendering, und @earendil-works/pi-telemetry mit anbieterneutralen Telemetrie-Verträgen, einem Referenzadapter, Konformitätstests und typisierten Schemas. Für Slack- und Chat-Automatisierung verweist das README auf das separate Repository earendil-works/pi-chat. Das Projekt ist TypeScript, MIT-lizenziert, zeigt nahezu 99.000 Sterne und wird mit Releases in der Reihe v0.84.4 aktiv weiterentwickelt.

Berechtigungen: bewusst keine, stattdessen drei Sandbox-Muster

Das README formuliert eine klare Grenze: Pi enthält kein eingebautes Berechtigungssystem für Dateisystem-, Prozess-, Netzwerk- oder Zugangsdatenzugriff. Standardmäßig läuft der Agent mit den Rechten des Benutzers und Prozesses, der ihn gestartet hat. Diese Offenheit ist Absicht, kein Versäumnis, denn das Projekt verweist stattdessen auf Containerisierung oder Sandboxing.

Dokumentiert sind in packages/coding-agent/docs/containerization.md drei Muster. Die Gondolin-Erweiterung belässt pi und die Anbieter-Authentifizierung auf dem Host und leitet eingebaute Tools sowie !-Befehle in eine lokale Linux-Mikro-VM um. Plain Docker führt den gesamten pi-Prozess in einem lokalen Container aus, für einfache Isolierung. OpenShell schließlich betreibt den gesamten Prozess in einer richtliniengesteuerten Sandbox. Die drei Varianten unterscheiden sich in der Grenzlage: bei Gondolin bleibt die Authentifizierung außen, bei den beiden anderen wandert alles hinein.

Entwicklung im Monorepo: von install --ignore-scripts bis test.sh

Der Entwicklungsweg beginnt mit npm install --ignore-scripts, das alle Abhängigkeiten ohne Lebenszyklusskripte installiert. Danach baut npm run build die Modelldaten neu und kompiliert alle Pakete, während npm run build:offline mit den vorhandenen Modelldaten ohne Netzwerkzugriff auskommt. npm run check bündelt Lint-, Format- und Typprüfungen.

Tests laufen über ./test.sh, das LLM-abhängige Tests automatisch überspringt, wenn keine API-Schlüssel gesetzt sind, und über ./pi-test.sh, das pi direkt aus den Quellen startet und von jedem Verzeichnis aus funktionieren soll. Diese beiden Skripte machen den Einstieg leicht: Ohne Anbieterkonto lässt sich der größte Teil der Testsuite ausführen, und die lauffähige CLI entsteht ohne Installationszyklus direkt aus dem Klon.

Standalone-Binaries aus Release-Quellen bauen

Die GitHub-Releases liefern ein versioniertes Quellarchiv, das von der SHA256SUMS-Datei des Releases abgedeckt wird. Daraus entstehen die eigenständigen Binaries mit demselben Skript wie für die offiziellen Builds: Archiv entpacken, dann ./scripts/build-binaries.sh --offline-model-data --platform linux-x64 --out "$PWD/out" ausführen.

Das Flag --offline-model-data baut mit den im Archiv mitgelieferten generierten Anbieter-Modelldaten statt sie aus Live-Katalogen zu aktualisieren, was den Build reproduzierbar macht. Das Skript installiert Abhängigkeiten, baut das Monorepo, kompiliert die Bun-Ausführungsdatei und legt die Laufzeit-Assets ab. Paketbetreuer, die Abhängigkeiten selbst bereitstellen, können --skip-install --skip-deps übergeben. Wie die Reproduktion beginnt, zeigt die Reihenfolge: Prüfsumme gegen SHA256SUMS, entpacken, bauen, erst dann ausführen.

Supply-Chain-Härtung: exakte Pins, Shrinkwrap und Audits

Das Projekt behandelt npm-Abhängigkeitsänderungen als zu prüfende Codeänderungen. Direkte externe Abhängigkeiten sind auf exakte Versionen festgelegt, interne Workspace-Pakete bleiben mit Versionsbereichen. Die .npmrc setzt save-exact=true und min-release-age=2, um Veröffentlichungen desselben Tages während der npm-Auflösung auszuschließen. package-lock.json gilt als Grundwahrheit, und ein Pre-Commit-Hook blockiert versehentliche Lockfile-Commits, sofern nicht PI_ALLOW_LOCKFILE_CHANGE=1 gesetzt ist.

Weiter geht die Kette: npm run check verifiziert die festgelegten direkten Abhängigkeiten, die native TypeScript-Importkompatibilität und den generierten Shrinkwrap des Coding-Agenten. Das veröffentlichte CLI-Paket enthält packages/coding-agent/npm-shrinkwrap.json, um transitive Abhängigkeiten für npm-Nutzer festzunageln. Die Shrinkwrap-Erzeugung führt eine explizite Zulassungsliste für Lebenszyklusskripte, neue Abhängigkeiten mit Skripten scheitern an den Prüfungen, bis sie geprüft wurden. CI installiert mit npm ci --ignore-scripts, und ein geplanter GitHub-Workflow läuft npm audit --omit=dev sowie npm audit signatures --omit=dev. Release-Rauchtests nutzen npm run release:local, um isolierte npm- und Bun-Installationen außerhalb des Repositorys zu bauen.

Beitragen unter Sonderregeln und geteilte Sitzungen

Neue Issues und Pull Requests von neuen Beitragenden werden standardmäßig automatisch geschlossen, die Maintainer sichten die automatisch geschlossenen Issues täglich. Die Beitragsrichtlinien stehen in CONTRIBUTING.md, projektspezifische Regeln für Menschen und Agenten in AGENTS.md. Langfristige Pläne pflegt das Projekt in RFCs unter rfc.earendil.com/keyword/pi/.

Ein zweiter Aufruf richtet sich an Nutzer: Wer Coding-Agenten für Open-Source-Arbeit einsetzt, soll die Sitzungen veröffentlichen, denn echte Aufgaben, Tool-Nutzung, Fehler und Fixes verbessern die Agenten besser als Spielzeug-Benchmarks. Das Werkzeug dafür ist badlogic/pi-share-hf, benötigt werden ein Hugging-Face-Konto, die Hugging-Face-CLI und pi-share-hf selbst. Der Maintainer veröffentlicht eigene pi-mono-Sitzungen als Datensatz auf Hugging Face.

Fazit: ein Harness, der Grenzen dem Nutzer überlässt

Pi verkauft keine Sicherheitsgarantie mit, sondern dokumentiert, wo sie fehlt, und liefert drei konkrete Isolierungsmuster samt Build-Werkzeugen nach. Das ist die eigentliche Haltung dieses Projekts: Der Harness ist offen, die Grenzen gehören dem Betreiber, und die Lieferkette wird mit Pins, Shrinkwrap und Audits eng gehalten.

Passen wird das allen, die einen Anbieter-neutralen Agenten in eigene Abläufe integrieren wollen und bereit sind, Sandboxing selbst zu entscheiden. Wer eine fertig abgeschottete Lösung sucht, findet sie hier nicht vorgefertigt. Vor dem Aufbau empfiehlt sich der Weg aus den Quellen: Klonen, npm install --ignore-scripts, npm run build, dann ./pi-test.sh, und parallel die Containerisierungsdokumentation lesen, bevor der erste echte Auftrag läuft.

Redaktionelles Fazit

Pi eignet sich für Entwickler, die einen selbst erweiterbaren Coding-Agenten mit freier Anbieterwahl suchen und bereit sind, Isolierung selbst zu organisieren, etwa über die dokumentierten Muster Gondolin, Docker oder OpenShell. Wer eine fertige Berechtigungsverwaltung erwartet, schaut an dieser Stelle ins Leere, das README sagt das ausdrücklich voraus. Vor dem produktiven Einsatz lohnt ein Blick auf packages/coding-agent/docs/containerization.md und ein Testlauf mit ./pi-test.sh aus den Quellen, um die gewählte Sandbox-Variante gegen die eigenen Tools zu prüfen.

Offizielle Quellen

1. Official README
2. Project repository
3. Release notes