Vergiss OpenCode. PI Agent Harness ist 10x besser.

Das Transkript wurde mithilfe von KI‑Tools erstellt. Web Clipper → Obsidian → Copilot, unter lokaler Verwendung von gpt‑oss:120b auf einem Mac Studio.

2025 ist das Jahr des Coding-Agenten. Seit OpenAI im April die Codex-CLI als Open-Source-Projekt veröffentlicht hat, sind Terminal-Agenten wie Claude Code, Cursor und OpenCode nacheinander zu den «Co-Piloten» in der täglichen Arbeit von Entwicklern geworden.

Wenn du kein Medium-Abonnement hast, kannst du über diesen Link den vollständigen Artikel lesen. Das ist die Quelle für diesen Blog, ich habe den mit KI-Tools übersetzt und dann selber nachbearbeitet.
Quelle für diesen Blog: Gao Dalie

Ehrlich gesagt liegt es daran, dass ich genug von Claude Code habe. Ich liebe Claude Code. Es ist ein Produkt, das die Programmierung prägt, und das Team ist grossartig. Aber die Ausgabe ist immer fehlerhaft.

Ich spreche nicht von Fehlern. Mein Arbeitsablauf wird gestört, weil sich der Harness ändert und sich dadurch auch das Verhalten des Modells ändert.

Als Ingenieur benötige ich zuverlässigere Werkzeuge. Natürlich ist es etwas ironisch, das im Jahr 2026 zu sagen, denn die LLMs selbst sind unzuverlässig. Trotzdem kann ich zumindest Teile davon deterministisch machen, und ich möchte das auch tun, einschliesslich der Werkzeuge, System-Prompts und allem, was in sie eingespeist wird.

Wenn du dir Claude Code oder OpenAIs Codex ansiehst, bemerkst du, dass sie heimlich vieles in deinen Kontext packen, ohne es dir in der Benutzeroberfläche zu zeigen. Diese Dinge stören deinen Arbeitsablauf auf sehr subtile Weise.

Ihre Veröffentlichungszyklen betragen einen Tag oder sogar mehrere Veröffentlichungen pro Tag. Du kannst um 9 Uhr mit der Arbeit beginnen, der Arbeitsablauf funktioniert perfekt, dann bricht er um 10 Uhr zusammen, und um 15 Uhr verhält sich alles völlig anders. Das Modell hat sich nicht geändert, nur der Harness. Unter diesen Umständen kann ich nicht arbeiten.

Claude Code, OpenCode und Codex: Nahezu jeden Monat werden neue Funktionen zu Coding-Agenten hinzugefügt. MCP, Subagenten, Planmodus, Ausführung im Hintergrund. Die Möglichkeiten haben zugenommen. Gleichzeitig wird es immer schwieriger, den Überblick darüber zu behalten, was hinter den Kulissen geschieht.

Pi Codding Agent geht gegen diesen Trend. Auf GitHub hat es mehr als 99'000 Sterne. Sein Ersteller, Mario Zechner, ist ein Ingenieur, der für das Java-Spiele-Framework bekannt ist. Er war mit den bestehenden Coding-Agenten unzufrieden und schrieb deshalb einen von Grund auf neu für sich selbst.

Das Designprinzip lautet: «Wenn ich es nicht benötige, wird es nicht entwickelt.» Bestehende Werkzeuge schleusen im Hintergrund Kontext ein, sodass der Benutzer nicht sehen kann, was geschieht. Das war seine Motivation.

Was hat Pis minimalistisches Design inspiriert?

Bevor Mario über Pi schrieb, überprüfte er die Rangliste von Terminal Bench. Dort gab es einen Harness namens Terminus, der bemerkenswert war. Er stellt LLMs lediglich ein Werkzeug zur Verfügung, mit dem sie mit der tmux-Sitzung interagieren können.

Das LLM muss einzelne Tastatureingaben senden und die von tmux zurückgegebene ANSI-Sequenz lesen, um die Aufgabe abzuschliessen. Mit diesem einzigen Werkzeug landet es fast immer unter den ersten drei und häufig auf dem ersten Platz.

Das vermittelte mir eine entscheidende Erkenntnis: Modelle werden inzwischen intensiv mit bestärkendem Lernen trainiert. Deshalb wissen sie von Natur aus, was ein Coding-Harness ist, ohne dass man zu viel darauf aufbauen muss. Pi ist die Verkörperung dieser Idee: ein minimalistischer, aber skalierbarer Harness.

Was den Pi-Agenten einzigartig macht

Das Auffällige an Pis Design ist, dass es absichtlich Funktionen weglässt, die andere Coding-Agenten normalerweise besitzen.

Es geht nicht darum, dass nicht genug vorhanden ist. Ich habe mich entschieden, es nicht hinzuzufügen.

Zechner stellt MCP in seinem Blog infrage. Das Problem ist nicht das Protokoll selbst, sondern der Tokenverbrauch. Playwright MCP verwendet 21 Werkzeuge und 13'700 Token und verbraucht damit 7 bis 9 Prozent des Kontextfensters. Chrome DevTools MCP verwendet 26 Werkzeuge und 18'000 Token.

Wenn du dich mit einem MCP-Server verbindest, werden in jeder Sitzung alle Werkzeugdefinitionen in den Kontext geladen. CLI-Werkzeuge haben READMEs. Du musst sie nur lesen und ausführen, wenn es notwendig ist. Es gibt keinen Grund, ständig Kontext zu verbrauchen.
Mario Zechner: What I learned building an opinionated and minimal coding agent

Dasselbe gilt für Subagenten. Claude Code startet intern Subagenten und gibt nur ein zusammengefasstes Ergebnis zurück. Was im Inneren geschehen ist, ist von aussen nicht sichtbar. pi verwendet tmux, um Instanzen nebeneinander anzuzeigen. Alle Interaktionen sind für Menschen direkt lesbar.

Eine weitere Kritik an bestehenden Harnesses lautet, dass sich System-Prompts und Werkzeugdefinitionen häufig ändern, sodass die Benutzer keine Kontrolle darüber haben, welcher Kontext eingespeist wird. pi begrenzt System-Prompts auf weniger als 1'000 Token und legt ihren Inhalt vollständig offen.

Das beständige Prinzip lautet, dass der Harness den Arbeitsablauf nicht diktieren sollte. Wenn etwas fehlt, sollte der Benutzer es selbst erstellen.

Was in OpenCode und Claude Code fehlt

pi wurde nach einem subtraktiven Ansatz entwickelt, verfügt aber auch über Funktionen, die Claude Code fehlen.

Modellwechsel während einer Sitzung

Der Context in pi wird in einem anbieterunabhängigen Format serialisiert. Selbst wenn du mit Anthropic beginnst und mitten in der Arbeit zu OpenAI wechselst, bleibt der Kontext erhalten. Mit /model oder Ctrl+L kannst du sofort wechseln.

Auch den Umgang mit dem Denken haben wir standardisiert. Claudes erweitertes Denken, OpenAIs Reasoning-Aufwand und Geminis Denkbudget werden alle auf einer fünfstufigen Skala von minimal bis xhigh dargestellt.

JSONL Tree Session

Der Sitzungsverlauf wird im JSONL-Format gespeichert. Jeder Eintrag verfügt über eine id und eine parentId, wodurch eine Baumstruktur entsteht. Mit dem Befehl /tree kannst du zu jedem beliebigen Punkt in der Vergangenheit zurückkehren und von dort aus einen anderen Zweig erweitern.

Das ähnelt Git-Zweigen, aber der Verlauf passt in eine einzige Datei. Wenn du zu einem früheren Ansatz zurückkehren möchtest, musst du die Sitzung nicht von Anfang an neu beginnen.

PiPops

Erweiterungen, Skills, Prompt-Vorlagen und Themes können gemeinsam über npm oder git verteilt werden.

pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi config  # Aktivieren oder deaktivieren

Das Werkzeug selbst verfügt über einen integrierten Mechanismus, mit dem die Community Erweiterungen erstellen und teilen kann.

Erweiterungsmechanismus

Der Grund, weshalb Pi auch mit eingeschränktem Funktionsumfang verwendet werden kann, liegt darin, dass es drei Möglichkeiten zur Erweiterung seiner Fähigkeiten gibt.

Erweiterungen bieten die grösste Flexibilität. Du kannst sie in TypeScript schreiben und eigene Werkzeuge, Befehle, Tastenkürzel und Ereignis-Handler hinzufügen. Du kannst Hooks vor und nach Werkzeugaufrufen einfügen. So kann beispielsweise eine Erweiterung geschrieben werden, die gefährliche Befehle blockiert.

import { ExtensionAPI } from "@mariozechner/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName = "bash"
        && event.input.command.includes("rm -rf")) {
      const ok = await ctx.ui.confirm(
        "Gefährlich!", "rm -rf erlauben?"
      );
      if (!ok) return { block: true, reason: "Blockiert" };
    }
  });
}

Wir haben das Berechtigungsbestätigungsfenster von Claude Code nicht entfernt. Wir haben lediglich ermöglicht, dass Benutzer Code nach ihren eigenen Kriterien erstellen können.

Skills sind SKILL.md-Dateien, die dem Agent-Skills-Standard entsprechen und denselben Spezifikationen folgen wie die Skills in Claude Code.

Prompt-Vorlagen sind wiederverwendbare Markdown-Dateien, die mit /templatenameerweitert werden können. Mustache-Variablen ({{variable}}) können ebenfalls verwendet werden.

1. Grundlegende Installation

Die Installation erfolgt mit einem einzigen Befehl.

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Eine weitere Möglichkeit besteht darin, ein Installationsskript zu verwenden.

curl -fsSL https://pi.dev/install.sh | sh

Es gibt zwei Authentifizierungsmöglichkeiten.

# Einen API-Schlüssel verwenden
export ANTHROPIC_API_KEY=sk-ant-...
pi

# Ein bestehendes Abonnement verwenden 
pi 
/login  # Einen Anbieter auswählen

Mit /login können bestehende Abonnements wie Anthropic Claude Pro/Max, OpenAI ChatGPT Plus/Pro (Codex) und GitHub Copilot unverändert verwendet werden.

Der wichtigste Punkt dieses Videos ist, dass die Lernkurve äusserst flach ist.
Installiere es einfach und interagiere damit, dann beginnt es zu funktionieren.

2. Modelle einrichten

Dieser Teil des Videos nahm am meisten Zeit in Anspruch, etwa 9 Minuten. Pi unterstützt mehr als 15 verschiedene LLM-Anbieter. Hier sind einige der wichtigsten:

- Anthropic
- OpenAI
- Google Gemini / Vertex
- DeepSeek
- xAI
- OpenRouter
- Amazon Bedrock
- Azure OpenAI
- Groq / Cerebras / Mistral usw.

Modelle mitten in einer Sitzung zu wechseln, ist völlig normal.

/model # Bildschirm zur Modellauswahl 
Ctrl+L # Dasselbe wie oben 
Shift+Tab # Denkstufe wechseln (off bis max)

Benutzerdefinierte Anbieter können unter ~/.pi/agent/models.json hinzugefügt werden. Wenn sie mit OpenAI-, Anthropic- oder Google-kompatiblen APIs arbeiten, funktionieren sie nach entsprechender Konfiguration. Du kannst auch Router-Server wie llama.cpp für dein lokales Modell verbinden.

Ein Vorteil, den Pi stark hervorhebt, ist, dass es «nicht an einen Anbieter gebunden» ist.

3. Sitzungsverwaltung

Pi-Sitzungen werden als JSONL-Datei mit Baumstruktur gespeichert. Der Speicherort wird festgelegt, wobei sich unter ~/.pi/agent/sessions/ separate Speicherorte für jede Nachricht befinden.idparentId

Dank dieser Struktur können alle folgenden Vorgänge innerhalb einer einzigen Datei ausgeführt werden:

pi -c   # Die letzte Sitzung fortsetzen
pi -r   # Aus früheren Sitzungen auswählen

Dies sind die wichtigsten Befehle während einer Sitzung.

Besonders interessant ist /tree. Du kannst zu «jeder beliebigen Stelle» in der Unterhaltung zurückkehren und von dort aus einen neuen Zweig erstellen, um weiterzuschreiben. Der gesamte Verlauf wird in einer Datei gespeichert, sodass du sofort feststellen kannst: «Oh, ich wollte so weitermachen wie vor 30 Minuten.»

/compact fasst alte Nachrichten zusammen und komprimiert den Kontext.
Standardmässig ist auch die automatische Komprimierung aktiviert. Bei einem Überlauf des Kontexts wird der Vorgang automatisch wiederhergestellt und erneut versucht.

4. Plugin-Erweiterungen

Hier kommt Pi wirklich zur Geltung. Dieser Teil wurde im Video etwa 10 Minuten lang behandelt. Die Anpassung von Pi besteht aus vier Ebenen.

Erweiterungen (TypeScript)
→ Werkzeuge, Befehle, Benutzeroberfläche und Ereignisverarbeitung

Skills
→ In Markdown verfasste Abläufe und Anweisungen

Prompt-Vorlagen
→ Wiederverwendbare Prompts

Themes
→ Darstellungsthemen

pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi list
pi update --all

Mit Erweiterungen kannst du unter anderem Folgendes tun:

• Benutzerdefinierte Werkzeuge hinzufügen, einschliesslich des Ersetzens integrierter Werkzeuge.
• Subagenten und Planmodi individuell erstellen.
• Berechtigungskontrollen und Pfadschutz einrichten.
• Elemente der Benutzeroberfläche wie Statuszeile, Kopfzeile und Fusszeile hinzufügen.
• Git-Prüfpunkte und automatische Commits einrichten.
• MCP-Server integrieren.
• Während des Wartens sogar Doom ausführen.

Der entscheidende Punkt des Videos ist, dass alle Funktionen, die andere Agenten direkt in das Produkt integriert haben, etwa Subagenten, Planmodus und Berechtigungsfenster, mithilfe von Erweiterungen erstellt werden können.

Daher besteht die Designphilosophie von Pi darin, den Kern minimal zu halten.

5. Skills

Skills sind «Fähigkeitspakete», die in Markdown-Dateien verfasst werden.
Gemäss dem Agent-Skills-Standard bildet ein Ordner mit einer SKILL.md-Datei einen Skill.

<!-- ~/.pi/agent/skills/my-skill/SKILL.md -->
# Mein Skill
Verwende diesen Skill, wenn ein Benutzer nach X fragt.

text
## Schritte
## 1. Führe diese Aktion aus.
## 2. Führe danach jene Aktion aus.

Zusätzlich zur expliziten Verwendung über /skill:name lädt der Agent einen Skill automatisch, wenn die Aufgabe dazu passt.

Der entscheidende Punkt ist, dass Skills nur bei Bedarf in den Kontext geladen werden. Statt alles in den System-Prompt zu packen, werden sie erst bei ihrer Verwendung erweitert. So bleibt der System-Prompt mit 1'000 Token erhalten.

6. Pi Web, die Browser-Benutzeroberfläche

Das Video enthielt ausserdem eine Einführung in die Browser-Benutzeroberfläche «Pi Web».

npx @agegr/pi-web@latest

Dies sind die wichtigsten Funktionen:

• Sitzungsarbeitsbereich: Frühere Unterhaltungen nach Projekt auflisten, fortsetzen, umbenennen und löschen.
• Zwei Verzweigungsmöglichkeiten: Eine neue Sitzung aus einer Nachricht erstellen oder innerhalb der aktuellen Sitzung einen Zweig erstellen.
• Projektdateien anzeigen und Git-Diffs darstellen.
• Git-Worktrees wechseln.
• Anbieteranmeldung sowie Modell-, Paket- und Skill-Konfiguration über das Web.

Da ~/.pi/agent dieselben Einstellungs- und Sitzungsdateien wie die Terminalversion von pi verwendet, ist es praktisch, jederzeit zwischen Browser und Terminal zu wechseln.

7. Speichersystem

Die Organisation der mit Videos verbundenen «Erinnerungen» erwies sich als überraschend einfach.

Unsere Haltung lautet, dass für Pi keine separate Datenbank für Langzeitspeicher erforderlich ist.

1. Die Sitzung selbst ist der Speicher
Der gesamte Verlauf wird als JSONL gespeichert und kann
jederzeit fortgesetzt werden.

2. AGENTS.md / CLAUDE.md
Schreibe Projektkonventionen, Anweisungen und Befehle in
diese Dateien. Sie werden beim Start aus den globalen
Einstellungen und der Verzeichnishierarchie geladen.

3. Komprimierung
Lange Sitzungen werden durch eine Zusammenfassung älterer
Teile komprimiert. Der vollständige Verlauf bleibt jedoch
in JSONL erhalten, sodass du mit /tree zurückgehen kannst.

Mit anderen Worten werden die Aufgaben folgendermassen aufgeteilt: «Was wir getan haben» wird von der Sitzung verwaltet, und «Was du beachten sollst» wird in AGENTS.md festgehalten.

Daraus folgt, dass das Hinzufügen einer Speicherfunktion über eine Erweiterung ebenfalls ein häufiger Anwendungsfall ist.

8. Sichere Verwendung

Pi verfügt über keine integrierte Sandbox. Lese-, Schreib-, Bearbeitungs- und Bash-Vorgänge werden mit den Berechtigungen des Benutzers ausgeführt, der Pi gestartet hat. Dasselbe gilt für Erweiterungen.

Dies ist eine bewusste Designentscheidung. Eine unausgereifte Sandbox innerhalb des Prozesses bietet nur eine «scheinbar sichere Grenze». Deshalb besteht die offizielle Haltung darin, echte Isolation dem Betriebssystem sowie Container- und VM-Ebenen zu überlassen.

Im Video wurde betont, dass nicht vertrauenswürdige Repositorys und unbeaufsichtigte Ausführung immer in einer isolierten Umgebung erfolgen sollten.

# 1. Die gesamte Pi-Umgebung in Docker ausführen (am einfachsten)

# 2. Pi auf dem Host ausführen und nur die Werkzeugausführung 
#    an eine lokale Micro-VM (Gondolin) weiterleiten 
pi -e ~/.pi/agent/extensions/gondolin

Es gibt einen weiteren Mechanismus namens Projektvertrauen. Dabei handelt es sich um eine «Schutzvorrichtung beim Einlesen von Eingaben», die verhindern soll, dass Repositorys Pi-Einstellungen oder Erweiterungen beliebig überschreiben. Standardmässig wird bei nicht verifizierten Projekten eine Bestätigung verlangt.

Es ist jedoch wichtig zu beachten, dass dadurch Prompt-Injection nicht vollständig verhindert wird. Bei der Arbeit mit nicht näher bestimmten Codebasen oder Dokumenten musst du dies bei der Verwendung dieser Methode berücksichtigen.

9. Eigene Plugins erstellen

Der letzte Teil des Videos, etwa 5 Minuten, ist der Implementierungsabschnitt, in dem du «deine eigene Erweiterung schreibst».

Die kleinste Erweiterung besteht aus einer einzigen TypeScript-Datei.

export default function (pi: ExtensionAPI) {
  pi.registerTool({
    name: "deploy",
    // Werkzeugdefinition (Eingabeschema, Ausführungslogik)
  });

pi.registerCommand("stats", { 
 // Definition eines benutzerdefinierten Befehls   });

pi.on("tool_call", async (event, ctx) => {    
 // Werkzeugaufrufe abfangen und verarbeiten
}); }

Wenn du diese Datei unter ~/.pi/agent/extensions/ ablegst, entweder für die gesamte Benutzergruppe, oder projektbezogen unter .pi/extensions/, wird sie beim Start von Pi automatisch geladen. Für einen einmaligen Test verwendest du einfach pi -e ./my-ext.ts.

Das offizielle Repository enthält zahlreiche Beispiele für automatische Commits, Git-Prüfpunkte, MCP-Integration und benutzerdefinierte Komprimierung. Bei Pi gilt: «Die gewünschte Funktion ist nicht enthalten.» Das Standardverfahren besteht deshalb darin, sie entweder selbst hinzuzufügen oder ein Paket zu installieren.

Mein Eindruck

Das können wir von Pi lernen:

Je mehr Funktionen du hinzufügst, desto mehr Prozesse werden für den Benutzer unsichtbar. Subagenten, Ausführung im Hintergrund und automatische Komprimierung sind zwar praktisch, erhöhen aber die Anzahl der Blackboxes. pi legt Wert darauf, dass Menschen alle Interaktionen direkt beobachten können.

Wenn du selbst einen Agenten entwickelst, werden Pis Designentscheidungen zu einem Referenzpunkt. Beginne nicht mit einem Komplettpaket, sondern mit vier Werkzeugen und einem System-Prompt mit 1'000 Token. Füge nur hinzu, was du benötigst. Das Design beginnt nicht mit der Frage, was hinzugefügt werden soll, sondern mit der Frage, was entfernt werden kann.

Gao Dalie: Ich bin ein Experte für generative KI! Wenn du an einem Projekt zusammenarbeiten möchtest, sende mir eine  Anfrage  oder buche einen  Beratungstermin