Pi, das Minimal Coding Agent Harness: Erweiterungen, Fähigkeiten, Sitzungen und Sicherheit
Warum ein kleines Terminal-Code-Toolset mit vier Werkzeugen und einer kurzen Systemanzeige Agenten mit vielen Funktionen übertrifft: Installation, Modelle, Sitzungsbäume, Erweiterungen, Fähigkeiten und Sandboxing.
Terminal-Code-Tools wie Claude Code, Cursor und OpenCode sind zu einem normalen Bestandteil des Tages vieler Entwickler geworden, insbesondere seit OpenAI im April die Codex CLI freigegeben hat. Pi, ein absichtlich einfaches Code-Tool, entstand aus der Kritik an all diesen Tools: Die Tools ändern ständig ihre Funktionsweise.
Es geht dabei nicht um Fehler. Vielmehr ändern sich die Tools, und dadurch ändert sich auch das Verhalten des Modells. Ingenieure möchten Tools, auf die sie sich verlassen können. LLMs an sich sind unzuverlässig, doch zumindest die umgebenden Komponenten – einschließlich der Tools, der Systemanweisungen und allem, was in sie eingefügt wird – können deterministisch gestaltet werden.
Claude Code und Codex fügen viel Kontext hinzu, ohne dies in der Benutzeroberfläche anzuzeigen, und diese versteckten Ergänzungen stören den Arbeitsablauf auf subtile Weise. Updates erscheinen einmal am Tag oder sogar mehrmals am Tag. Ein Arbeitsablauf, der um neun Uhr morgens perfekt funktioniert, kann bereits um zehn zusammenbrechen und um drei völlig anders funktionieren – obwohl das Modell unverändert bleibt und nur die Schnittstelle anders ist. Neue Funktionen werden fast jeden Monat hinzugefügt, darunter MCP, Subagenten, Planungsmodus und Hintergrundausführung, wodurch es immer schwieriger wird, mitzubekommen, was im Hintergrund geschieht.
Pis Lösung ist eine Gestaltungsregel: Wenn etwas nicht benötigt wird, wird es nicht implementiert. Bestehende Tools fügen Kontext unsichtbar hinzu, sodass die Nutzer nicht erkennen können, was vor sich geht. Das war die Motivation.
Was den Minimalismus inspiriert hat
Bevor Pi entwickelt wurde, schaute sein Schöpfer, Mario Zechner, sich auf der Terminal Bench Leaderboard um, wo ein Tool namens Terminus hervorstach. Es stellt dem Modell genau ein Werkzeug zur Verfügung – eine Schnittstelle zu einer tmux-Sitzung. Das LLM sendet einzelne Tasteneingaben und liest die ANSI-Ausgabe von tmux zur Erfüllung der Aufgabe zurück. Mit nur diesem Werkzeug erreicht es fast immer einen der drei ersten Plätze und belegt oft den ersten Platz.
Das weist auf eine nützliche Intuition hin: Modelle werden heutzutage stark mithilfe von Verstärkungslernen trainiert, sodass sie bereits wissen, was ein Programmierwerkzeug ist, und nicht viel zusätzlich benötigen. Pi verkörpert diese Idee als ein minimalistisches, aber erweiterbares Werkzeug.
Was macht Pi besonders
Das Besondere an Pi ist das, was es weglässt – Eigenschaften, die andere Programmierwerkzeuge als Standard betrachten. Nehmen wir MCP: Man verbindet sich mit einem Server, und jede Tool-Definition überflutet zu Beginn jeder Sitzung den Kontext. CLI-Tools kommen mit READMEs, die nur dann gelesen und ausgeführt werden, wenn sie benötigt werden, sodass es keinen Grund gibt, ständig Kontext dafür zu verbrauchen.
Was Pi hat, was andere nicht haben
Pi wurde durch Weglassen entwickelt, besitzt aber Fähigkeiten, die Claude Code nicht hat. Erweiterungen und Pakete werden mit wenigen Befehlen installiert:
pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi config # Enable or disable
Der Erweiterungsmechanismus
Erweiterungen werden anhand einer aus dem Pi-Paket importierten API entwickelt:
import { ExtensionAPI } from "@mariozechner/pi-coding-agent";
Eine Erweiterung kann sich an Ereignisse wie Tool-Aufrufe anschließen. Ein Beispiel schützt vor gefährlichen Shell-Befehlen:
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(
"Dangerous!", "Allow rm -rf?"
);
if (!ok) return { block: true, reason: "Blocked" };
}
});
}
1. Installation
Die Installation erfordert nur einen Befehl:
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
Ein Installationsskript ist eine Alternative:
curl -fsSL https://pi.dev/install.sh | sh
Es gibt zwei Möglichkeiten zur Authentifizierung. Eine verwendet einen API-Schlüssel:
# Use an API key
export ANTHROPIC_API_KEY=sk-ant-...
pi
Die andere nutzt ein Abonnement, das Sie bereits haben:
# Use an existing subscription
pi
/login # Select a provider
Mit /login können bestehende Abonnements wie Anthropic Claude Pro oder Max, OpenAI ChatGPT Plus oder Pro (Codex) sowie GitHub Copilot unverändert genutzt werden. Die Einarbeitungszeit ist sehr kurz: Installieren Sie es, beginnen Sie mit dem Gespräch damit – und es funktioniert.
2. Modellkonfiguration
Pi unterstützt mehr als 15 Anbieter von LLMs. Zu den wichtigsten gehören:
- Anthropic
- OpenAI
- Google Gemini / Vertex
- DeepSeek
- xAI
- OpenRouter
- Amazon Bedrock
- Azure OpenAI
- Groq / Cerebras / Mistral など
Das Wechseln der Modelle mitten in einer Sitzung ist völlig normal:
/model # Model selection screen
Ctrl+L # Same as above
Shift+Tab # Switch thinking level (off–max)
Custom Provider können in ~/.pi/agent/models.json hinzugefügt werden. Jede mit OpenAI, Anthropic oder Google kompatible API funktioniert allein durch Konfiguration, und Router-Server wie llama.cpp können lokale Modelle bereitstellen. Dass man „nicht an einen bestimmten Provider gebunden ist“, ist einer der Vorteile, den Pi am stärksten hervorhebt.
3. Sitzungsverwaltung
Sitzungen werden als baumstrukturierte JSONL-Datei unter ~/.pi/agent/sessions/ gespeichert, wobei jede Nachricht über die Felder id und parentId verfügt. Aufgrund dieser Struktur unterstützt eine einzige Datei alle diese Operationen:
pi -c # Continue the most recent session
pi -r # Select from previous sessions
Der Befehl /tree ist besonders interessant. Man kann zu jedem Punkt der Konversation zurückkehren und von dort aus fortfahren. Die gesamte Historie befindet sich in einer Datei, sodass es einfach ist, zu sagen „Ich möchte den Weg nehmen, den ich vor einer halben Stunde genommen habe“ und dies tatsächlich umzusetzen.
/compact fasst alte Nachrichten zusammen, um den Kontext zu komprimieren. Die automatische Komprimierung ist standardmäßig aktiv, und falls der Kontext überläuft, wird dies automatisch korrigiert und neu versucht.
4. Erweiterungen im Detail
Hier zeigt Pi, wofür es wirklich da ist. Die Anpassungsmöglichkeiten haben vier Ebenen:
Extensions (TypeScript) → Tools, commands, UI, and event handling
Skills → Procedures/instructions written in Markdown
Prompt Templates → Reusable prompts
Themes → Display themes
Pakete von npm oder git werden wie folgt verwaltet:
pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi list
pi update --all
Erweiterungen können alles Folgende tun:
- Custom-Tools hinzufügen, einschließlich Ersatzteilen für die integrierten Tools.
- Custom-Sub-Agenten sowie Planungsmodi erstellen.
- Rechtlich festgelegte Zugriffsregeln sowie Schutzmechanismen für Pfade durchsetzen.
- Interfacedetails wie Statuszeile, Header und Footer hinzufügen.
- Git-Checkpointe oder automatische Commit-Vorgänge erstellen.
- MCP-Server integrieren.
- Falls gewünscht, während des Wartens Doom ausführen.
Der entscheidende Punkt ist, dass jede Funktion, die andere Agenten in das Produkt einbauen – einschließlich Sub-Agenten, Planungsmodi und Berechtigungsdialogfelder – als Erweiterung erstellt werden kann. Die Philosophie besteht daher darin, den Kern möglichst minimal zu halten.
5. Fähigkeiten
Fähigkeiten sind in Markdown geschriebene Pakete von Fähigkeiten. Gemäß dem Agent Skills-Standard bildet ein Ordner mit einer SKILL.md-Datei eine solche Fähigkeit.
<!-- ~/.pi/agent/skills/my-skill/SKILL.md -->
# My Skill
Use this skill when a user asks about X.
```
```text ## Steps 1. Perform this action. 2. Then perform that action. ```
Eine Fähigkeit kann explizit mit /skill:name aufgerufen werden, und der Agent lädt sie außerdem eigenständig, wenn die Aufgabe dazu passt. Die entscheidende Gestaltungsentscheidung besteht darin, dass Fähigkeiten nur dann in den Kontext aufgenommen werden, wenn sie benötigt werden. Anstatt alles in den Systemprompt zu packen, werden sie beim Gebrauch aktiviert, wodurch der Systemprompt bei etwa tausend Tokens bleibt.
6. Pi Web, die Browser-Oberfläche
Es gibt außerdem eine Browser-Schnittstelle namens Pi Web:
npx @agegr/pi-web@latest
Seine Hauptfunktionen:
- Eine Sitzungsarbeitsfläche zum Auflisten, Wiederaufnehmen, Umbenennen und Löschen früherer Gespräche nach Projekt.
- Zwei Möglichkeiten zum Branchen: Eine neue Sitzung von einer Nachricht aus starten oder innerhalb der aktuellen Sitzung forken.
- Anzeige von Projektdateien sowie Git-Diff-Unterschiede.
- Wechsel zwischen Git-Worktrees.
- Anmelden beim Anbieter sowie Einstellungen für Modelle, Pakete und Fähigkeiten im Browser.
Da es die ~/.pi/agent-Einstellungen und Sitzungsdateien mit der Terminalversion teilt, ist der Wechsel zwischen Browser und Terminal problemlos.
7. Speicher
Der Speicher ist eigentlich einfach gestrickt. Die Ansicht ist, dass Pi keine separate Langzeit-Speicheldatenbank benötigt. Stattdessen gibt es drei Mechanismen:
1. The session itself is memory
The entire history is saved as JSONL and can be resumed at any time.
2. AGENTS.md / CLAUDE.md
Write project conventions, instructions, and commands in these files.
They are loaded at startup from global settings and the directory hierarchy.
3. Compaction
Long sessions are compressed by summarizing older parts.
However, the complete history remains in JSONL, so you can go back with /tree.
Anders ausgedrückt: Was bereits erledigt wurde, bleibt in der Sitzung gespeichert, und was man im Gedächtnis behalten möchte, befindet sich in AGENTS.md. Das Hinzufügen von Speicher durch eine Erweiterung ist ebenfalls ein häufiges Anwendungsbeispiel.
8. Sicher bleiben
Der Pi verfügt über keinen eingebauten Sandbox. Lese-, Schreib-, Bearbeitungs- und Bash-Operationen laufen mit den Rechten dessen, der ihn gestartet hat – genauso wie bei Erweiterungen. Das ist absichtlich so. Ein halb eingebauter In-Process-Sandbox bietet nur eine scheinbar sichere Grenze, weshalb die offizielle Haltung darin besteht, die eigentliche Isolierung dem Betriebssystem sowie den Container- oder VM-Schichten zu überlassen. Unzuverlässige Repositorien sowie unbeaufsichtigte Ausführungen sollten in einer isolierten Umgebung stattfinden.
Eine Möglichkeit besteht darin, die gesamte Pi-Umgebung in Docker zu platzieren – das einfachste Vorgehen:
# 1. Put the entire pi environment in Docker (simplest)
Eine weitere Möglichkeit besteht darin, Pi auf dem Host zu betreiben und die Ausführung von Tools nur an eine lokale Micro-VM weiterzuleiten:
# 2. Run pi on the host and route only tool execution
# to a local micro-VM (Gondolin)
pi -e ~/.pi/agent/extensions/gondolin
Eine Funktion namens Project Trust fügt einen Eingabenschutz hinzu. Sie verhindert, dass Repositorien die Pi-Einstellungen oder Erweiterungen heimlich überschreiben, und fragt standardmäßig nach Bestätigung bei unüberprüften Projekten. Allerdings verhindert sie nicht vollständig die Eingabeinjektion, daher sollten Sie dies im Hinterkopf behalten, wenn Sie mit unbekannten Code- oder Dokumenten arbeiten.
9. Ihre eigene Erweiterung schreiben
Die kleinste Erweiterung besteht aus einer einzigen TypeScript-Datei. Sie registriert ein Tool:
export default function (pi: ExtensionAPI) {
pi.registerTool({
name: "deploy",
// Tool definition (input schema, execution logic)
});
und es kann Befehle hinzufügen oder Aufrufe von Tools abfangen:
pi.registerCommand("stats", {
// Custom command definition }); pi.on("tool_call", async (event, ctx) => {
// Intercept tool calls and process them
}); }
Legen Sie die Datei in ~/.pi/agent/extensions/ für alle Projekte oder in .pi/extensions/ für ein einzelnes Projekt, dann wird sie beim Start von Pi automatisch geladen. Für einen einmaligen Test reicht pi -e ./my-ext.ts. Im offiziellen Repository finden Sie viele Beispiele: automatische Commit-Vorgänge, Git-Checkpointe, MCP-Integration sowie benutzerdefinierte Komprimierungsfunktionen. Auf Pi ist das Fehlen bestimmter Funktionen üblich. Normalerweise fügen Sie diese selbst hinzu oder installieren ein Paket.
Was Pi lehrt
Für alle, die ihren eigenen Agent entwickeln, bieten Pi’s Entscheidungen eine nützliche Referenz. Vermeiden Sie Pakete mit zu vielen Funktionen. Beginnen Sie mit vier Werkzeugen sowie einem Systemprompt mit etwa tausend Tokens und fügen Sie nur das hinzu, was wirklich benötigt wird. Die Gestaltung beginnt damit, was entfernt werden soll, und nicht damit, was hinzugefügt werden soll.
Weitere Literatur
- Die fünf Ebenen eines Agent Harness – mit Code, der ohne sie fehlschlägt – Eine praktische Übersicht über die fünf Stellen, an denen ein Agent Harness Regeln im Code durchsetzt, von Ausführungsgrenzen bis zu Kontextpipelines, sowie darüber, was die Forschung beweisen kann und was nicht.
- Praktische Anmerkungen: Erstellung eines Private Cloud Coding Agents – OpenCode + ein lokales LLM – Eine schrittweise Anleitung zu den Praktischen Anmerkungen zur Erstellung eines Private Cloud Coding Agents: OpenCode + ein lokales LLM, einschließlich Verträgen, Überprüfungen sowie Code-Blöcken, die Teams zur Implementierung dieses Musters verwenden können.