Pi installieren - dein erster Agent im Terminal

Pi (auch pi-coding-agent) ist ein Terminal-Agent von Mario Zechner. Anders als Claude Code oder Cursor ist Pi bewusst minimal gebaut: ein paar Hundert Token Systemprompt, vier eingebaute Werkzeuge - read, write, edit, bash - und ansonsten leerer Tisch. Erweitert wird Pi nicht durch eine fette Featureliste, sondern durch zwei einfache Mechanismen: eine AGENTS.md, die Pi automatisch liest, und sogenannte Skills, die du selber als Markdown-Dateien schreibst.

Genau diese Reduktion macht Pi zum ehrlichen Einstiegs-Agenten: du verstehst, was passiert, weil so wenig passiert. Und du verstehst, wie Agenten generell funktionieren, weil Pi keine Magie zwischen dich und das Modell schiebt.

Am Ende dieses Tutorials hast du:

• Pi installiert und einen ersten Chat geführt
• Pi mit einem Endpunkt deiner Wahl verbunden - lokal (Ollama) oder kostenlos in der Cloud (Groq, OpenRouter, Anthropic-Probelauf)
• Verstanden, wie Pi sein Verhalten aus deiner AGENTS.md lernt
• Einen eigenen Skill geschrieben und ausgeführt
• Drei fertige Beispiel-Skills heruntergeladen, die du sofort einbauen kannst

Was ist Pi eigentlich?

Bevor wir installieren, ein Bild davon, was Pi ist und was nicht.

Pi ist ein dünner Layer zwischen dir und einem Sprachmodell. Du tippst eine Aufgabe ins Terminal, Pi schickt sie an ein LLM, das LLM antwortet entweder mit Text oder ruft eines der vier Werkzeuge auf. Pi führt den Werkzeug-Aufruf aus (eine Datei lesen, eine Datei schreiben, einen Bash-Befehl ausführen), gibt das Ergebnis ans Modell zurück, und das Spiel wiederholt sich, bis die Aufgabe erledigt ist.

Pi ist nicht ein abgekapselter Coding-Bot. Trotz des Namens Coding-Agent funktioniert Pi für jede dateiorientierte Aufgabe: Tagebuch führen, Notizen sortieren, Newsletter kuratieren, CSVs auswerten, Foto-Ordner aufräumen, Wartungslogbücher schreiben. Alles, was auf deinem Rechner als Datei existiert, kann Pi anfassen.

Pi ist nicht automatisch sicher. Im Standardmodus führt Pi jeden Befehl aus, den das Modell vorschlägt. Das ist bewusst so - die Sicherheits-Diskussion gehört aber an den Anfang, nicht ans Ende des Tutorials. Mehr dazu in Schritt 7.

Schritt 1 - Pi installieren

Pi gibt es als One-Liner-Skript oder als npm-Paket. Beide installieren das gleiche.

Per Installer-Skript (empfohlen für macOS/Linux):

Per npm (alle Plattformen, Node.js 18+ vorausgesetzt):

Beide Wege legen ein Binary namens pi in deinem Pfad an. Schnelltest:

Windows-Setup

Pi läuft auf Windows, braucht aber zwei Dinge zusätzlich, weil Pi intern Bash-Befehle aufruft (das bash-Tool des Agenten):

1. Git for Windows installieren. Das bringt bash.exe mit, die Pi automatisch findet (C:\Program Files\Git\bin\bash.exe). Download: git-scm.com/download/winExtern - Öffnet in neuem Tab - Standard-Installer durchklicken, Defaults sind okay.

Pi sucht beim Start in dieser Reihenfolge nach einer Bash:

1. Eigener Pfad in ~/.pi/agent/settings.json (Feld shellPath)
2. Git Bash (C:\Program Files\Git\bin\bash.exe)
3. bash.exe aus dem PATH (auch Cygwin, MSYS2, WSL)

Für die meisten Fälle reicht Git Bash. Wer WSL bevorzugt, installiert Pi am besten direkt innerhalb von WSL - dort gilt dann der Linux-Pfad (curl … | sh).

2. Node.js installieren. Am bequemsten über den offiziellen Installer von nodejs.orgExtern - Öffnet in neuem Tab (LTS-Variante). Nach der Installation in Windows Terminal (siehe unten) prüfen: node --version und npm --version.

Dann Pi installieren - gleicher npm-Befehl wie oben, in PowerShell oder Git Bash:

Schritt 2 - Wähle einen Endpunkt

Pi ist nur die Hülle. Das eigentliche Denken macht ein Sprachmodell, das du anstöpselst. Du hast drei realistische Wege, völlig kostenlos zu starten:

Variante A - Lokal mit Ollama (empfohlen, kein Account nötig)

Wenn du das Ollama-Tutorial und das Hermes-Tutorial durchgespielt hast, hast du bereits einen lokalen Endpunkt unter http://localhost:11434. Pi spricht das direkt an - du musst Pi nur einmal sagen, wo das Modell wohnt.

Lege folgende Datei an (oder lade die Beispiel-models.json unten):

apiKey muss laut Spezifikation gesetzt sein, Ollama ignoriert den Wert. Das compat-Feld ist wichtig: viele OpenAI-kompatible Server (darunter Ollama, vLLM, SGLang) verstehen den developer-Rollen-Marker und das reasoning_effort-Feld nicht, das Pi sonst standardmäßig schickt - beide Flags auf false schaltet das ab.

Variante B - Kostenlos in der Cloud mit Groq

Wenn du keinen leistungsfähigen Rechner hast oder einfach nur schnell etwas ausprobieren willst: Groq bietet einen großzügigen Free-Tier ohne Kreditkarte. Du bekommst 30 Anfragen/Minute und 14.400 Anfragen/Tag pro Modell - mehr als genug zum Lernen - und Groq ist extrem schnell (500-800 Tokens pro Sekunde, weil sie spezielle Inferenz-Chips, sogenannte LPUs, verwenden).

1. Auf console.groq.comExtern - Öffnet in neuem Tab registrieren (Mailadresse reicht).
2. Unter API Keys einen neuen Schlüssel erstellen.
3. Schlüssel als Umgebungsvariable setzen:

Groq ist in Pi als Provider eingebaut. Du wählst das Modell nach dem Start mit /model. Empfehlenswerte freie Modelle bei Groq für Agent-Tasks:

• llama-3.3-70b-versatile - Allzweck, sehr stabil bei Tool-Use.
• llama-3.1-8b-instant - schneller, leichter, gut für kurze Tasks.

Variante C - Anthropic-Probelauf (Claude)

Wenn du einen Anthropic-Account hast (auch ohne aktives Pro-Abo gibt es Probierkredite), funktioniert Pi out-of-the-box mit Claude:

Alternativ login per OAuth direkt aus Pi heraus mit /login, wenn du eine Claude-Pro- oder Claude-Max-Subscription hast.

Schritt 3 - Erste Konversation

Starte Pi einfach mit:

Beim ersten Aufruf siehst du eine Begrüßung, eine Statuszeile am Fuß (Arbeitsverzeichnis, aktuelle Session, geladene AGENTS.md, ausgewähltes Modell) und einen Eingabe-Cursor.

Wechsle in das Modell, das du eingerichtet hast - Tastenkürzel Ctrl+L oder Befehl /model. Tippe dann eine Aufgabe:

Du siehst Pi denken (kurzer Status), dann den geplanten Werkzeug-Aufruf (write), den Pfad, den Inhalt. Bestätigung war im Default-Modus nicht nötig - Pi schreibt direkt.

Das wirkt unscheinbar, ist aber der Kern. Ein Modell hat eigenständig entschieden, dass write das richtige Werkzeug ist, die Argumente formuliert, und Pi hat den Aufruf ausgeführt. Das ist ein Agent.

Schritt 4 - AGENTS.md verstehen

Pi schiebt fast nichts in seinen Systemprompt. Was Pi immer lädt, ist eine AGENTS.md-Datei. Sogar mehrere, von oben nach unten konkateniert:

1. ~/.pi/agent/AGENTS.md (global, gilt überall)
2. AGENTS.md in allen Eltern-Ordnern (vom aktuellen Ordner aufwärts bis zum Home)
3. AGENTS.md im aktuellen Ordner

Das ist eine leise, aber mächtige Mechanik: du kannst pro Lebensbereich (z.B. ~/Kunden/X/AGENTS.md, ~/Tagebuch/AGENTS.md) einen eigenen Verhaltens-Kanon hinterlegen, ohne irgendwo zu schalten oder zu konfigurieren. Pi findet die Datei selbst und merkt sich, was drinsteht.

Erstelle deine globale Datei:

Ein guter Start-Inhalt - du kannst die Beispiel-AGENTS.md unten direkt herunterladen und anpassen:

Starte Pi neu (oder /reload im laufenden Pi) und probiere etwas, das du vorher schon mal getan hattest:

Pi sollte jetzt zuerst kurz erklären, was er tut, und nicht sofort schreiben. Du hast Pi mit einer einzelnen Markdown-Datei umerzogen. Das ist der Hebel.

Schritt 5 - Dein erster Skill

Ein Skill ist eine Markdown-Datei, die ein Stück Aufgabenwissen kapselt. Wenn dein Prompt zu dem passt, was im Skill-Header beschrieben ist, lädt Pi den Inhalt des Skills nur dann in seinen Kontext (Pi-Sprech: progressive disclosure). Das spart Tokens und hält das Modell fokussiert.

Skills folgen einem offenen Standard von agentskills.ioExtern - Öffnet in neuem Tab. In Pi gehört jeder Skill in einen eigenen Ordner mit einer SKILL.md darin:

Inhalt der SKILL.md (oder lade SKILL-journal.md aus den Downloads herunter und verschiebe sie als SKILL.md):

/reload in der laufenden Pi-Session, oder Pi neu starten. Im Startbild steht jetzt „skills: tagebuch". Probiere es:

Pi erkennt das Wort Tagebuch, lädt den Skill, fragt vielleicht nach fehlenden Details (Wetter, Tags), und legt dann ~/Tagebuch/2026-05-10.md korrekt strukturiert an. Du kannst denselben Skill explizit erzwingen mit /skill:tagebuch.

Schritt 6 - Skills für deinen Alltag

Wir haben drei produktionsfertige Skills als Download vorbereitet. Jede Datei kommt mit Anweisungen, in welchen Ordner sie als SKILL.md gehört:

• Tagebuch-Skill - der eben gezeigte, in voller Länge.
• Meeting-Notes-Skill - verwandelt ein Transkript oder Stichpunkte in strukturierte Meeting-Notizen mit - [ ] Aufgaben-Listen, die du später per ripgrep filtern kannst.
• Newsletter-Kurations-Skill - gruppiert gespeicherte Artikel thematisch, schreibt pro Cluster eine 4-Satz-Einordnung.

Lade sie unten, lege je einen Ordner unter ~/.pi/agent/skills/<name>/ an, benenne die Datei in SKILL.md um.

Schritt 7 - Sicherheit zuerst denken

Im Standardmodus führt Pi jeden Werkzeug-Aufruf direkt aus. Das ist bewusst so - der Entwickler von Pi hält Bestätigungs-Popups für eine Quelle von Aufmerksamkeits-Erosion. Du musst aber wissen, was du tust:

• bash ist mächtig. Ein halluzinierter rm -rf ~/wichtig ist genauso schnell ausgeführt wie ein ls.
• write überschreibt. Pi kann eine bestehende Datei mit anderem Inhalt überschreiben, wenn er glaubt, dass das die Aufgabe verlangt.
• AGENTS.md ist deine erste Verteidigungslinie. Schreib dort verbindliche Verbote rein („niemals .env lesen", „vor rm immer fragen") - das Modell nimmt diese Regeln ernst.

Für den Anfang reichen drei Schutzmaßnahmen:

1. Starte Pi nur in Ordnern, in denen du Dateien verlieren könntest ohne dass dir etwas Schlimmes passiert. Niemals in ~/, niemals in einem Git-Repo mit ungesicherten Änderungen.
2. Versioniere wichtige Ordner (git init und regelmäßig git commit). So lässt sich jeder Pi-Fehler zurückrollen.
3. Setze in deiner globalen AGENTS.md die Regel: „Vor rm, mv, git push, git reset --hard, oder dem Anlegen von Dateien außerhalb des aktuellen Ordners: immer fragen." Pi befolgt das in der Praxis sehr zuverlässig.

Schritt 8 - Telemetrie und Update-Checks abschalten (optional)

Pi pingt beim Start zwei Endpunkte: einen für die Versions-Prüfung, einen für eine anonyme Install-/Update-Telemetrie. Beide kannst du ausschalten - entweder einzeln über Umgebungsvariablen oder global per settings.json.

Zusätzlich oder alternativ in deiner Shell:

Für lokal-only Setups ist PI_OFFLINE=1 der saubere Schalter. Pi funktioniert dann komplett ohne Internet - vorausgesetzt, dein Modell läuft auch lokal.

Schritt 9 - Sessions, Branches, Resume

Jede Pi-Konversation wird automatisch unter ~/.pi/agent/sessions/ als JSONL-Datei gespeichert. Das hat zwei nützliche Konsequenzen.

Erstens - Resume. Pi schließen und später weitermachen geht trivial:

Zweitens - Branches. Eine Pi-Session ist nicht linear, sondern ein Baum. Mit dem Befehl /tree (oder Escape zweimal) öffnest du den Baum-Navigator und kannst zu jedem früheren Punkt der Session zurückspringen - ohne den Rest zu verlieren. Tippst du danach eine neue Nachricht, entsteht ein neuer Zweig.

Das ist die Pi-Variante von „Was wäre, wenn ich an Stelle X anders gefragt hätte?". Bei einem Beratungs-Setup, einer Konflikt-Vorbereitung oder einer experimentellen Architektur-Diskussion ist das pures Gold - du musst nichts neu starten.

Schritt 10 - Print-Mode für Skripte und Cron-Jobs

Pi muss nicht interaktiv laufen. Mit -p (für print) bekommst du eine einmalige Antwort und einen Exit-Code:

Das öffnet die Tür zu Automation: ein nächtlicher Cron-Job, der die Wochenende-Reflexion vorbereitet; ein Git-Hook, der Pi eine Commit-Message vorschlagen lässt; ein Skript, das aus eingehenden E-Mails Aufgaben extrahiert.

Pi liest in Print-Mode auch Standard-Input - du kannst Pi also nach Lust und Laune in Unix-Pipes hängen:

Geschafft - wie geht's weiter?

Drei Richtungen, in die du jetzt weitergehen kannst:

• Mehr Skills bauen. Jede Aufgabe, die du dreimal pro Woche machst, ist ein Skill-Kandidat. Schreibe sie in dem Moment, in dem du sie das nächste Mal manuell tust.
• Modelle vergleichen. Wechsel mit /model zwischen einem kleinen lokalen Modell und einem Cloud-Modell und beobachte, wo der Unterschied wirklich spürbar ist (Hint: bei strukturierten Aufgaben oft kaum, bei kreativen Texten dramatisch).
• Pi anpassen. Lege eine AGENTS.md in jedem Lebensbereich an - ~/Kunden/<firma>/AGENTS.md, ~/Familie/AGENTS.md, ~/Projekte/<repo>/AGENTS.md. Pi schaltet automatisch zwischen den Verhaltensweisen, sobald du in einen anderen Ordner wechselst.

Troubleshooting

„command not found: pi" - entweder ist die globale npm-Bin nicht im PATH, oder das Installer-Skript hat das Binary woanders abgelegt. Prüfe npm config get prefix und ergänze ggf. $(npm config get prefix)/bin im PATH.

„Provider … not authenticated" - der Umgebungsvariablen-Name muss exakt stimmen (ANTHROPIC_API_KEY, GROQ_API_KEY, OPENAI_API_KEY, …). Pi liest die Variable beim Start, nicht während der Session - also Shell neu öffnen oder Pi-Restart nach export.

Antwort kommt, aber kein Tool-Use - kleine Modelle (z.B. llama3.2:3b) machen oft Klartext-Antworten statt Tool-Aufrufe. Wechsel auf ein größeres oder explizit auf Tool-Use trainiertes Modell (hermes3:8b, qwen2.5-coder:7b, llama-3.3-70b-versatile bei Groq).

Pi findet die AGENTS.md nicht - ~ wird vom Shell expandiert, nicht von Pi. Wenn du in einem Skript die Datei anlegst, nutze $HOME/.pi/agent/AGENTS.md statt ~/.pi/agent/AGENTS.md.

Skill wird nicht geladen - drei häufige Ursachen: (1) Datei heißt nicht exakt SKILL.md, (2) Skill-Ordner liegt nicht direkt unter ~/.pi/agent/skills/, (3) der „Wann nutzen"-Abschnitt ist zu vage. Mache den Trigger explizit (Schlüsselwörter, die der Nutzer wahrscheinlich schreibt).

Ollama-Verbindung schlägt fehl - prüfe in einem zweiten Terminal curl http://localhost:11434 (sollte „Ollama is running" zurückgeben). Bei nicht-default-Port den baseUrl-Wert in models.json anpassen.