Pi's kern is de Agent Loop, model-aanroep, tools en een terminalinterface. Je hebt Skills, Prompt Templates, Extensions en Packages nodig, ze passen gewoon op elkaar.
Bovendien, als je al aan het spelen is met Codex, Claude Code of Agent Skills, is Pi nog steeds de moeite waard om te leren.
Zo weinig het ook lijkt, de Agent ondergrond is uiteindelijk lezen, schrijven, wijzigen en uitvoeren. Veel complexere functionaliteiten kunnen uit deze basisprimitieven groeien.
Veel Agent producten bieden al vooraf een planningsmodus, sub-Agents, MCP, toestemmingsoverzichten en taaklijsten. De gebruiker moet alleen de instellingen aanpassen.
Pi geeft je een werkende Agent frame. Je kunt de Agent zelf aanpassen. Wil je een planningsmodus, gebruik dan bestanden of installeer een Extension. Wil je sub-Agents, gebruik tmux om meerdere Pi's te starten, of schrijf zelf een Extension. Wil je MCP aansluiten, dan kun je ook de juiste Extension installeren.
Het lijkt op een al geheel en al water en stroomgeleverde bouwkerk. Of je het comfortabel vindt, hangt af van hoe je het verder installeert.
Installatie
Methode 1: Geef de Agent de taak om het te installeren
Als je al Codex, Claude Code of andere Agenten gebruikt die de terminal kunnen bedienen, stuur dan de volgende volledige tekst aan hem:
Gebruik de huidige computeromgeving om Pi Coding Agent te installeren en te valideren:
1. Controleer eerst het besturingssysteem, CPU-architectuur, Node.js, npm en de daadwerkelijk actieve node en npm in de PATH;
2. Pi vereist Node.js >= 22.19.0. Als dit niet voldaan is, geef eerst de upgrade-mogelijkheid aan, maar maak geen directe wijzigingen aan mijn omgeving;
3. Installeer de officiële npm-pakket @earendil-works/pi-coding-agent, behoud de aanbevolen optie --ignore-scripts;
4. Na installatie verifieer met pi --version en pi --help;
5. Lees geen, print geen, wijzig geen API Key of inloggegevens;
6. Vertel me hoe je met /login kunt inloggen bij een bestaande abonnement, en hoe je in een lege testmap een alleen-lezen-verificatie kunt uitvoeren;
7. Als er problemen optreden, controleer eerst de officiële repository en de website-documenten, ga geen parameters raden.
Methode 2: Installeer zelf, stap voor stap
Stap 1: Controleer Node.js en npm
Op macOS, Linux open de terminal, op Windows PowerShell. Voer eerst uit:
node -v
npm -v
De Node.js-eis voor de officiële npm-pakketten van Pi is:
>= 22.19.0
Als node -v lager is dan deze versie, update dan eerst Node.js. Voor vrienden die zowel nvm, Homebrew als het systeem Node.js hebben geïnstalleerd, is er nog wat meer te overleggen:
which node
which npm
Soms denk je dat je geupgraded hebt, maar de terminal nog steeds de oude versie gebruikt. Dit is een veelvoorkomende valkuil in CLI-tools.
Windows heeft nog een extra vereiste. Pi draait standaard via Git Bash, dus een installatie van Git for Windows voldoet.
Let op: de optie --ignore-scripts moet behouden blijven. Dit voorkomt dat afhankelijkheden in de installatiefase levenscyclusscripten uitvoeren, wat voor Pi niet nodig is.
De website biedt ook een script voor één-kliksinstallatie:
curl -fsSL https://pi.dev/install.sh | sh
Deze opties zijn allemaal mogelijk. Maar curl | sh is echt het eenvoudigste.
Na installatie verifieer:
pi --version
pi --help
Per 12 september 2026 is de huidige versie in de officiële repository 0.85.1. Het project evolueert snel, een versienummer dat niet overeenkomt is niet per se een installatiemislukking. Kijk dan eerst naar GitHub Releases en de lokale pi --version.
De Quick start op de officiële website is ook dit commando.
Waarom lukt het niet om te starten?
Een veelvoorkomende situatie is dat de terminal meldt:
pi: command not found
Je kunt eerst de terminal afsluiten en opnieuw openen, en dan de globale installatielocatie van npm controleren:
npm config get prefix
npm list -g --depth=0
Als de lijst al @earendil-works/pi-coding-agent bevat, betekent dit dat de pakketten waarschijnlijk zijn geïnstalleerd, maar de globale executiedirectory van npm niet in de PATH staat. Voor macOS en Linux moet je de bin-directory in de globale prefix controleren, voor Windows de npm-globale directory.
Een andere probleemsoort is dat de Node.js-versie correct lijkt, maar tijdens het uitvoeren van Pi de oude omgeving wordt gebruikt. Controleer dan de volgende items samen:
which node
which npm
which pi
node -v
pi --version
Als pi geopend kan worden maar de modellijst leeg is, voer dan eerst /login uit, selecteer daarna het model. Je kunt ook de terminal afsluiten en controleren:
pi --list-models
Stap 3: Login aan de model
Start direct:
pi
Na het openen ziet de interface vrij simpel uit: in het midden is de invoerbalk, en onderaan wordt de huidige map, context en model weergegeven.
Na inloggen in de terminalinterface voer je:
/login
Pi laat je kiezen tussen modelproviders. Officieel ondersteunt het meer dan 15 providers, zowel via API Keys als via bestaande abonnementen.
Als je ChatGPT Plus of Pro hebt, kun je OpenAI Codex selecteren; ook GitHub Copilot wordt ondersteund. Claude Pro/Max kan worden ingelogd, maar er is een speciale opmerking: derde-partij Harness-aanroepen gebruiken Anthropic's extra gebruik, wat extra kosten in tokens met zich meebrengt en niet direct het abonnementsbedrag verbruikt. Dit moet je zeer in de gaten houden.
Voor vrienden die DeepSeek API gebruiken, kun je de sleutel in een omgevingsvariabele verstrekken:
export DEEPSEEK_API_KEY=je sleutel
pi
Maar voor beginners is het nog steeds aanbevolen om in Pi te login via /login. De gegevens worden opgeslagen in ~/.pi/agent/auth.json.
Na succesvolle login kun je de model en de denkgraad instellen met:
/model
/thinking
Ctrl+L kan ook snel de modelkeuzemogelijkheid openen, Shift+Tab kan de denkgraad instellen.
Stap 4: Voer een alleen-lezen-check uit
Ga naar een map waar je wilt testen, en voer de volgende instructie uit:
pi --tools read,grep,find,ls -p "Lees de huidige map, vertel mij wat het project doet, waar de ingang is en wat er moet worden uitgevoerd. Modificeer geen bestanden."
Hier gebruikte Pi de Print-modus, na het voltooien van de taak sluit het direct af; --tools beperkt de beschikbare tools tot lezen. Controleer dan drie zaken: of de model verbinding kan maken, of Pi de werkruimte kan lezen, of de toolbeperkingen effectief zijn.
Als je alleen enkele bestanden wilt bekijken, kun je ze ook direct meegeven:
pi -p @README.md "Vertel in het platte taal wat de installatie en start van dit project zijn"
Pi ondersteunt ook het bekijken van afbeeldingen:
pi -p @screenshot.png "Kijk naar deze foutpagina en geef me de volgorde voor het oplossen"
Stap 5: Verifieer de schrijfbare capaciteit
Maak een aparte testmap:
mkdir pi-playground
cd pi-playground
pi
Stuur de volgende minimale taak:
Gebruik eerst de huidige werkmap te controleren, en een lijst van bestaande bestanden te maken.
Maak vervolgens een hello-pi.md, met de volgende inhoud: de huidige tijd, de werkmap en de namen van de beschikbare tools.
Naast hello-pi.md, maak geen nieuwe, wijzigingen of verwijderingen.
Na voltooiing controleren de map opnieuw, en vertel mij wat er daadwerkelijk is veranderd.
Deze taak is niet technisch complex, maar ideaal voor verificatie. Het komt uit aan de orde van map-lezen, bestand-schrijven, beperkingen naleven en resultaatcontrole.
Na bevestiging dat alles correct werkt, kunnen we Pi met meer vertrouwen in een echte project gebruiken.
Als het project .pi/settings.json, .pi-resources of projectniveau Skills bevat, kan Pi vragen of je het huidige map vertrouwt.
Vertrouwen op het project betekent dat het projectconfiguratie, ontbrekende projectpakketten kan laden en project Extensions kan uitvoeren.
Herinner je deze veelgebruikte commando's van Pi
/login: Login of wissel modelprovider;
/model: Wissel model;
/thinking: Verander de denkgraad;
/new: Nieuwe sessie;
/resume: Voortzet een historische sessie;
/tree: Open de sessietree, spring naar een willekeurig punt;
/compact: Manueel compressie van de context;
/reload: Herlaad configuratie, Skills, extensies en thema;
/hotkeys: Toon alle sneltoetsen;
/session: Toon huidige sessiefil, ID, Token en kosten.
Ik vind de commando /tree heel belangrijk.
Voor normale chat als de richting vooruitloopt, kan de volgende sessie alleen opnieuw worden geopend. Pi's sessies worden in een boomstructuur opgeslagen, je kunt terugkeren naar een oude bericht en een nieuwe tak beginnen, de oude tak blijft in dezelfde JSONL-bestand.
Bijvoorbeeld: laat de Agent code reconstrueren, maar halveert de route, ga dan terug naar "begin reconstrueren" vóór en kies een andere optie. Zo voorkom je dat je de volledige context van de vorige sessie moet voeden. Vooral bij lange taken is deze functionaliteit erg nuttig.
De sessies worden standaard opgeslagen in:
~/.pi/agent/sessions/
Je kunt in de commando-lijn verder praten:
pi -c
pi -r
De eerste voegt voortaan de laatste sessie toe, de tweede laat je een historische sessie kiezen.
Toepassen in je eigen product
Pi kan niet alleen in de terminal chatten.
De officiële website heeft de gebruiksmogelijkheden van Pi onderverdeeld in vier groepen: Interactive, Print/JSON, RPC en SDK. Print en JSON passen bij programmaatige eenmalige of stroommatige taken, dus worden ze in dezelfde groep geplaatst.
Standaard start je pi en ga je in Interactive-modus, ideaal voor dagelijkse codewerk en lange taken.
Print-modus is geschikt voor eenmalige commando's:
pi -p "Controleer welke problemen dit project heeft"
JSON-modus geeft een continue uitvoer van gebeurtenissen, ideaal voor aansluiting op Shell-scripts, logsystemen of je eigen automatisering:
pi --mode json "Analyseer het huidige project"
RPC-modus ontvangt JSONL via standaardinput/output, ideaal om Pi in niet-Node.js-applicaties te integreren:
pi --mode rpc
Pi heeft ook SDK's. De ontwikkelaar kan in TypeScript-projecten een Agent Session aanmaken, en kan Pi als zijn eigen Agent Runtime zien.
Zo zie je dat je dezelfde kern hebt, maar in terminal, script, service en je eigen product gebruikt.
Three official examples to better understand Pi
De volgende drie voorbeelden komen van de officiële Pi-pagina. Ze zijn bedoeld om het te laten zien hoe deze Harness wordt gebruikt.
Case 1: A tree-shaped conversation
We hebben al gezegd dat Pi's sessies niet alleen een enkele chatstroom zijn. De officiële gedeelde sessiepagina toont links direct 241 knooppunten en verschillende takken; rechts kan de System Prompt, tools, berichten en callrecords worden uitgevouwen.
Dit is specifieker en praktischer dan "ondersteuning voor historische conversaties". Je kunt terugkeren naar een oude knooppunt en een nieuwe tak beginnen, of de volledige proces kunnen exporteren. Dit is voor
Case 2: Directly install others' extensions, skills and themes
Er is een Package Catalog op de Pi-website. Er zijn 5,435 items, met zowel MCP Adapters, webtoegang als workflows, databases en to-do components.
Dit zijn de mogelijkheden die je met pi install npm:<package> direct op je machine kunt installeren. In andere woorden, de extensie-ecosysteem van Pi is zeer rijk.
Case 3: Putting Doom into the terminal
Deze case is erg vreemd, maar toont het beste wat extensies kunnen bereiken. In de officiële demo voert de Agent achtergrondtaken uit, en wordt Doom direct ingebed in Pi's TUI! De uitvoering is echt goed, en de onderkant behoudt ook de model, Token, kosten en taakstatus.
Extensions kunnen events ontvangen, de interface aanpassen, nieuwe commando's en sneltoetsen registreren, en zelfs de hele interactielayer vervangen.
Skills worden stapsgewijs geladen. Tijdens start worden alleen de naam en beschrijving in de context geplaatst, de volledige SKILL.md wordt gelezen na task-matching, en niet alle uitleg wordt direct in de context gestopt.
Om een Skill te forceer uit te voeren, typ je:
/skill:skill-name
Dit ontwerp is gelijkwaardig aan de huidige Agent Skills-standaard. Veel Skills die je eerder voor Codex, Claude Code hebt gemaakt, kunnen hergebruikt worden.
Let Pi extend more capabilities
Skills oplossen "hoe", Extensions kunnen Pi zelf aanpassen, en zijn veel krachtiger.
Een Extension kan nieuwe tools, nieuwe commando's, nieuwe sneltoetsen en events registreren; kan de statusbar, editor, popups en thema aanpassen; kan sub-Agents, planningsmodus, toestemmingsgaten, Git-autosubmit, SSH-execution, sandboxes implementeren, en zelfs MCP aanvullen.
De Doom-demo op de officiële homepage is een duidelijk voorbeeld van een Extension.
De officiële aanbeveling: als je een specifieke functionaliteit mist, laat Pi het voor je schrijven.
Na aanpassing voer /reload uit, en je kunt verder met je huidige werk.
Als deze functionaliteit later nog moet worden hergebruikt, kun je Extension, Skill, Prompt en thema's in een Pi Package installeren:
pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi list
pi config
Opmerking: Een Pi Package is volledig anders dan een isolatieve extensie in een browser.
It's most often overlooked pitfall: default permission protection is not enabled
Pi geeft standaard geen toestemmingsoverzichten zoals sommige desktop Agents. Het erft direct de bestand, netwerk, credentials en systeemrechten van de proces die het start.
Dit is geen verborgen bug, de homepage van de officiële website heeft "No permission popups" duidelijk vermeld.
Voor mensen die bekend zijn met terminals betekent dit een yolo-modus, dus worden taken niet vaak onderbroken.
Voor beginners kan een onzorgvuldig Prompt echter wel tot problemen leiden, zoals het leegmaken van je C-schijf.
Voor beginners moet je de volgende punten letten:
Gebruik eerst een lege map, niet direct de desktop, documenten of de hele Home-map;
Lees code met --tools read,grep,find,ls beperkt tot alleen-lezen;
Laat de model geen ~/.pi/agent/auth.json, .env en andere credentials lezen;
Derde-partij Packages en Extensions eerst de broncode controleren voordat je ze installeert;
Als je het wilt laten langdurig automatisch lopen, zet het in een Docker, OpenShell of andere sandbox.
De officiële website geeft verschillende isolatieopties. De meest makkelijke is om de hele Pi in een Docker te zetten.
Let op: de gekoppelde werkmap kan nog steeds teruggeschreven worden naar de host; als je ook ~/.pi/agent van je eigen systeem koppelt, wordt de authenticatie en sessiebestanden ook aan de container gegeven.
Naast het starten controleert Pi nieuwe versies; na de eerste installatie of bij het detecteren van een upgrade, wordt ook een anonieme versie-informatie verzonden. Indien je dit niet wilt, kan je in de instellingen de installatietelemetrie uitschakelen, of gebruik:
PI_TELEMETRY=0 pi
Om de netwerkontschakeling volledig uit te schakelen:
PI_OFFLINE=1 pi
Who is Pi for?
Als je alleen een product wilt downloaden, inloggen, en dan in een veilige omheen veilig gebruik, is Pi misschien niet de makkelijkste keuze. Het heeft bewust sommige "gegeven" functionaliteiten weggehaald, veel dingen moeten zelf worden geconfigureerd.
Voor mensen die al meerdere modellen gebruiken, een aantal Skills hebben, de Agent willen integreren in scripts of producten, en die een basiscontrole van terminal en toestemming hebben, voelt het meer waarde. Vooral voor eenmansbedrijven en onafhankelijke ontwikkelaars.
Of de vrijheid hoger is, betekent dat je zelf meer moet controleren op het gebied van veiligheid.
