Pi coding agent è l'agente di programmazione da terminale che ha fatto la scelta opposta a tutti gli altri: invece di aggiungere funzioni, le ha tolte. Niente sotto-agenti, niente plan mode, niente popup dei permessi, niente MCP di serie. Al modello dà quattro strumenti (read, write, edit e bash) e tutto il resto lo costruisci tu con estensioni in TypeScript.
A settembre 2026 il repository ha superato le 107.000 stelle su GitHub e l'ultima release è la 0.85.
Io lavoro ogni giorno con Claude Code, ma Pi lo sto usando in un modo diverso: come motore agentico dentro un'applicazione desktop che sto sviluppando, pilotato via SDK da un processo Node.js. È un uso che spiega bene cosa lo rende speciale. In questa guida trovi cos'è Pi, come si installa, come si estende, cosa gli manca rispetto a Claude Code e OpenCode e quando secondo me conviene sceglierlo.
Cos'è Pi coding agent
Pi è un harness: lo strato di software che sta tra te e il modello linguistico e decide quali strumenti il modello può usare, come gestire il contesto e come salvare le sessioni. L'ha creato Mario Zechner, oggi il progetto è sotto l'organizzazione Earendil ed è rilasciato con licenza MIT.
Il monorepo contiene più pacchetti, ma i tre che contano sono:
- pi-coding-agent: la CLI interattiva, cioè l'agente che usi nel terminale.
- pi-agent-core: il runtime dell'agente con chiamate ai tool e gestione dello stato.
- pi-ai: un'API unificata per parlare con più provider (Anthropic, OpenAI, Google e altri) con lo stesso codice.
La filosofia è dichiarata: il core resta minimo e le funzioni che gli altri agenti hanno già dentro si aggiungono con estensioni, skill o pacchetti di terze parti. L'idea è che sia l'agente ad adattarsi al tuo modo di lavorare, e non il contrario.
Come installare Pi coding agent
L'installazione richiede Node.js e si fa con npm:
npm install -g --ignore-scripts @earendil-works/pi-coding-agentIl flag --ignore-scripts non è un dettaglio: disattiva gli script di installazione delle dipendenze, che sono uno dei punti d'ingresso degli attacchi alla supply chain npm. In alternativa c'è lo script ufficiale curl -fsSL https://pi.dev/install.sh | sh.
Poi entri nella cartella del progetto e lanci pi. Per collegare un modello hai due strade:
- Chiave API: esporti la variabile d'ambiente del provider, per esempio
ANTHROPIC_API_KEY. - Login: il comando
/logingestisce le credenziali dei provider supportati.
La lista dei provider è lunga: Anthropic, OpenAI, Google Gemini e Vertex, Amazon Bedrock, Mistral, Groq, DeepSeek, OpenRouter, xAI, Hugging Face, OpenCode Zen e Go e molti altri. Per i modelli in locale c'è il supporto al router di llama.cpp, gestibile con il comando /llama.
Un consiglio pratico: se pensi di usare un abbonamento consumer invece di una chiave API, leggi prima i termini del provider, perché non tutti permettono l'uso del piano fuori dal loro client ufficiale.
Come si usa: le quattro modalità
Pi coding agent gira in quattro modi diversi, ed è qui che si capisce perché piace a chi costruisce strumenti:
- Interattiva: la TUI nel terminale. Con
@cerchi i file del progetto, con!comandoesegui un comando e mandi l'output al modello, con/modelcambi modello a metà sessione. - Print o JSON:
pi -p "richiesta"risponde ed esce,--mode jsonemette tutti gli eventi come righe JSON. Perfetto per script e pipeline CI. - RPC:
pi --mode rpcparla JSONL su stdin e stdout, così lo integri da Python, Go o Swift. - SDK: importi
createAgentSessionda@earendil-works/pi-coding-agente crei sessioni dentro la tua app Node.js.
Sessioni ad albero
Le sessioni sono salvate come file JSONL con una struttura ad albero. Con /tree torni a qualsiasi punto della conversazione e riparti da lì, con /fork crei una nuova sessione da un messaggio precedente, con /export la esporti in HTML.
Quando un agente sbaglia strada dopo venti passaggi, poter tornare indietro senza perdere il lavoro è la differenza tra ripartire da zero e correggere il tiro.
AGENTS.md e prompt di sistema
All'avvio Pi carica AGENTS.md (oppure CLAUDE.md) dalla cartella globale, dalle cartelle padre e da quella corrente, e li concatena. Se hai già un progetto impostato per Claude Code, le istruzioni vengono lette senza toccare nulla. Il prompt di sistema si sostituisce con .pi/SYSTEM.md o si estende con APPEND_SYSTEM.md.
Estensioni, skill e pacchetti: come si aggiunge ciò che manca
Qui sta il cuore di Pi coding agent. Le estensioni sono moduli TypeScript che possono registrare tool, comandi, scorciatoie, gestori di eventi e componenti della TUI. Con un'estensione puoi aggiungere sotto-agenti, plan mode, conferme prima dei comandi pericolosi, protezione di cartelle, checkpoint git o una compaction su misura.
Accanto alle estensioni ci sono:
- Skill: seguono lo standard Agent Skills, quindi un
SKILL.mdscritto per Claude funziona anche qui. Si richiamano con/skill:nomeo le carica l'agente quando servono. Se non le hai mai scritte, parti dalla mia guida per creare una skill da zero. - Prompt template: file Markdown riutilizzabili che si espandono con
/nome. - Pi Packages: raccolte di estensioni, skill e template installabili con
pi installda npm o da git.
Un dettaglio che mi è piaciuto subito: puoi chiedere a Pi stesso di scriverti l'estensione che ti manca, poi dai /reload e la usi senza riavviare.
Cosa manca rispetto a Claude Code (e perché è voluto)
Rispetto a Claude Code, Pi coding agent rinuncia di proposito ad alcune cose:
- Nessun MCP di serie: l'autore preferisce strumenti da riga di comando descritti da una skill. Se ti serve MCP, lo aggiungi con un'estensione. Se vuoi capire cosa perdi, qui trovi la mia guida completa a MCP.
- Nessun sotto-agente: si fanno con istanze multiple in tmux o con un pacchetto.
- Nessun plan mode e nessuna to-do integrata: si scrive il piano in un file, oppure si installa un pacchetto.
- Nessun sistema di permessi: Pi gira con i permessi dell'utente che l'ha lanciato.
Il punto da non sottovalutare: la sicurezza
L'ultimo punto è quello che chiedo di leggere due volte. Senza popup di conferma, un agente che ha accesso a bash può cancellare, spostare o inviare qualsiasi cosa l'utente possa toccare.
La documentazione ufficiale lo dice chiaramente e propone tre strade: l'estensione Gondolin che esegue i tool in una micro VM Linux, un container Docker per l'intero processo, oppure OpenShell con policy di sicurezza. Su una macchina con chiavi, clienti e dati veri, io non lo lancerei senza una di queste tre.
Pi coding agent vs Claude Code vs OpenCode
Sono le due domande più cercate su Pi, quindi le metto a confronto in modo diretto:
- Claude Code: funziona subito, ha sandbox, permessi, hook, plugin e sotto-agenti pronti, e gira in terminale, desktop e IDE. Il limite è che usa solo i modelli Claude e il costo dipende dal piano: ne parlo in quanto costa Claude Code.
- OpenCode: open source, decine di provider, una TUI molto curata e funzioni già pronte come MCP e sotto-agenti. È la via di mezzo tra libertà e comodità: trovi il confronto dettagliato in Claude Code vs OpenCode.
- Pi: il più piccolo e il più controllabile. Prompt di sistema corto, quattro tool, tutto il resto è codice tuo. Richiede di saper scrivere un po' di TypeScript e di occuparti della sicurezza.
Esiste anche una quarta strada, opposta a Pi nella filosofia: DeepSeek Harness, dove tutto è un plugin e Claude Code diventa un sotto-agente. L'ho analizzato in DeepSeek Harness: Claude Code diventa un plugin.
Come lo uso io: Pi come motore dentro un'app
Il motivo per cui ho scelto Pi per il progetto su cui sto lavorando non è la CLI, è l'SDK. Mi serviva un loop agentico affidabile da incorporare in un'applicazione desktop, con i miei strumenti e le mie regole, senza portarmi dietro decisioni prese da altri.
L'impostazione che ho adottato è semplice da raccontare:
- Pi gira in un processo Node.js separato, dietro un adapter: l'app non dipende direttamente dalla sua API, così un aggiornamento non rompe tutto.
- I tool integrati di Pi sono disattivati: l'agente vede solo gli strumenti che registro io, ognuno con un controllo su cosa può fare.
- Le azioni che modificano qualcosa (pubblicare, cancellare, fare un deploy) passano sempre da un diff e da un'approvazione umana.
Con Claude Code questo tipo di controllo non l'avrei: è un prodotto finito, pensato per essere usato così com'è. Pi invece è un componente. La regola che mi sono dato è "Pi gestisce l'agente, l'app gestisce il progetto".
Se stai valutando di integrare un agente AI in un gestionale o in un prodotto, è il tipo di lavoro che faccio nei progetti di automazione AI e di sviluppo web app.
Quando scegliere Pi coding agent
- Sì, se vuoi incorporare un agente nella tua applicazione via SDK o RPC, se vuoi usare qualsiasi modello (anche in locale) senza vincoli, se ti serve controllare ogni token che entra nel contesto.
- Sì, se ti piace costruirti gli strumenti e sai lavorare in TypeScript.
- No, se vuoi un agente che funzioni subito, con permessi e sandbox già pronti: in quel caso Claude Code o OpenCode ti fanno risparmiare tempo.
- No, se non hai modo di isolarlo in un container: meglio non lanciarlo su una macchina con dati sensibili.
Leggi anche
- Claude Code vs OpenCode: quale scegliere nel 2026
- DeepSeek Harness: Claude Code diventa un plugin
- Claude Skills: come creare una skill da zero
- Claude Code gratis con Ollama e modelli locali
In sintesi
Pi coding agent non è l'agente più comodo del 2026, ed è proprio il suo punto. Quattro tool, un core piccolo, sessioni ad albero, SDK e RPC per incorporarlo dove vuoi: è il mattone giusto per chi vuole costruire un agente su misura, non per chi ne cerca uno pronto. L'unica condizione che non negozierei è l'isolamento: container o micro VM prima di dargli accesso a qualcosa di importante.
Se vuoi integrare un agente AI nel tuo software o nei processi della tua azienda e non sai da quale harness partire, scrivimi dal form contatti oppure a info@cosimo.dev: ti dico quale strada ha senso per il tuo caso.
