Un agente AI da terminale è un programma a cui descrivi un compito a parole e che lo esegue sul tuo computer: apre file, li modifica, lancia comandi. Quasi tutti arrivano con molte funzioni già decise ma con frequenti richieste di conferma. Pi, sviluppato da Earendil Inc. e distribuito con licenza MIT (libera, gratuita e modificabile), fa l’opposto. Si definisce un «agent harness» minimale, cioè un programma di base che collega un modello linguistico a pochi strumenti: leggere, scrivere e modificare i file ed eseguire comandi. Mancano di proposito i sub-agenti (assistenti secondari a cui l’agente principale affida una parte del lavoro), la plan mode (una fase in cui l’agente propone un piano e attende la tua approvazione) e i popup che chiedono il permesso. Se ti servono, li aggiungi con un’estensione, cioè un piccolo programma che amplia Pi.
Il progetto ha oltre 120.000 stelle su GitHub ed è arrivato alla versione 1.0. Funziona con più di quindici fornitori di modelli e accetta sia abbonamenti sia modelli installati sul tuo PC con Ollama. In questa guida vediamo come installarlo su Windows, come personalizzarlo un passo alla volta e come aggiungere un controllo che blocca i comandi pericolosi.
Come installare Pi su Windows e scegliere tra Bash e PowerShell
Il modo più semplice è l’installer ufficiale. Fissa le versioni di tutti i componenti di cui Pi ha bisogno, così il risultato è lo stesso su ogni computer, e permette di aggiornarlo con pi update. Da PowerShell basta una riga:
powershell -c "irm https://pi.dev/install.ps1 | iex"Pi richiede Node.js 22.19 o successivo (l’ambiente che esegue i programmi JavaScript), e l’installer può scaricarlo al posto tuo. In alternativa puoi usare npm, il gestore di pacchetti di Node.js. Con npm però i componenti secondari non vengono bloccati a una versione precisa, quindi aggiornamenti futuri possono cambiarne il comportamento. Aggiungi l’opzione --ignore-scripts, che impedisce ai pacchetti di eseguire comandi automatici durante l’installazione: a Pi non servono.
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi --versionPoi spostati nella cartella in cui vuoi lavorare e scrivi pi. Il primo comando da dare è /login: scegli un fornitore (OpenAI, Claude, OpenRouter, ecc.) e collega il tuo abbonamento oppure una chiave API (un codice personale che autorizza il programma a usare il servizio). Con /model cambi modello quando vuoi. Per indicare un file senza scrivere il percorso, digita @ e cerca il nome.
Su Windows resta da scegliere la shell, cioè il programma che eseguirà i comandi testuali (la riga di comando). Di default Pi usa Git Bash, quindi devi installare Git for Windows. Per controllare che funzioni, scrivi !printf 'Bash funziona\n' nell’editor di Pi. Se invece lavori soprattutto con PowerShell o con comandi tipici di Windows, puoi attivare lo strumento PowerShell nel file ~/.pi/agent/settings.json:
{
"defaultTools": ["read", "powershell", "edit", "write"]
}Per programmare lascerei bash, perché mi aspetto che i modelli conoscano meglio i comandi Unix e sbaglino di meno. Per gestire file e impostazioni del PC userei PowerShell. Come console classica, la documentazione raccomanda Windows Terminal.
Quali funzioni mancano a Pi e quali rischi comporta
Il sito di Pi ha una sezione intitolata «What we didn’t build», cioè «cosa non abbiamo costruito». Pi non ha sub-agenti: se ti servono, avvii più copie di Pi con tmux (un programma che tiene più terminali aperti insieme). Non ha un plan mode e non ha una lista di attività. Non ha comandi in background: anche qui si usa tmux. Recentemente Pi ha aggiunto il supporto a MCP, il protocollo che collega l’agente a programmi esterni, e include Codemode, che permette all’agente di eseguire più chiamate a questi programmi dentro un ambiente JavaScript isolato.
Il rischio maggiore, usando Pi, è l’assenza di richieste di permesso. Pi mostra ogni lettura, ricerca, comando e modifica, ma non chiede conferma prima di eseguire queste operazioni: gli strumenti hanno gli stessi permessi dell’utente che ha avviato Pi. Se il tuo computer contiene documenti di lavoro e chiavi SSH (i file che ti identificano sui server), un comando sbagliato del modello può cancellarli o copiarli. Lo stesso vale per un’istruzione nascosta in un file scaricato, che il modello può eseguire come se fosse tua.
Come personalizzare Pi
Per personalizzare Pi la documentazione consiglia di partire dal meccanismo più semplice e questa tabella li elenca dal più semplice al più complesso.
| Esigenza | Strumento |
|---|---|
| Istruzioni valide ogni volta che lavori in una cartella | AGENTS.md |
| Riusare una richiesta scritta una volta sola | Prompt template |
| Istruzioni per un tipo di lavoro, con file di supporto | Skill |
| Nuovi strumenti, comandi o controlli | Estensione |
AGENTS.md è un file di testo che Pi legge all’avvio. Lo cerca nella cartella ~/.pi/agent/, nelle cartelle che contengono quella di lavoro e nella cartella stessa. Pi legge anche CLAUDE.md, quindi un file scritto per altri agenti funziona senza modifiche. Un esempio per Windows:
# Regole per questo PC
- Rispondi in italiano, in modo sintetico.
- Prima di cancellare o spostare file, elenca cosa verrà toccato.
- Non toccare mai C:\Windows, né le cartelle .ssh e .aws.
- Per i percorsi usa le virgolette, perché molte cartelle contengono spazi.Un prompt template è una richiesta salvata in un file Markdown (testo semplice con una sintassi leggera per titoli ed elenchi) dentro ~/.pi/agent/prompts/. Il nome del file diventa un comando. Salvando il testo seguente come ordina.md, ottieni /ordina. L’argomento è facoltativo: se non lo scrivi, Pi usa la cartella corrente, rappresentata dal punto.
---
description: Proponi come riordinare una cartella
argument-hint: "[cartella]"
---
Analizza la cartella ${1:-.} e proponi uno schema di riordino per tipo e data.
Non spostare nulla: mostra una tabella con vecchio e nuovo percorso.Una skill è una cartella con un file SKILL.md che spiega a Pi come svolgere un tipo di lavoro, per esempio «convertire un PDF in testo». All’avvio Pi legge solo nome e descrizione. Carica le istruzioni complete quando il compito lo richiede, oppure puoi attivare tu la skill con /skill:nome. La descrizione è importante, perché il modello la usa per decidere se la skill serve.
Come bloccare i comandi pericolosi con un’estensione
Le estensioni sono file TypeScript (un linguaggio di programmazione) che girano dentro Pi. Mettile in ~/.pi/agent/extensions/ e /reload le carica subito. Il repository ufficiale include un esempio, il «permission gate» (blocco con permesso), che chiede conferma prima di comandi come rm -rf, che cancella intere cartelle, o sudo, che esegue comandi da amministratore. Funziona così: l’estensione si collega all’evento tool_call, cioè il momento in cui l’agente sta per usare uno strumento, e può fermarlo restituendo { block: true }. Ecco una variante per Windows che controlla sia bash sia PowerShell:
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
export default function (pi: ExtensionAPI) {
const pericolosi = [
/\brm\s+(-rf?|--recursive)/i,
/\bRemove-Item\b.*-Recurse/i,
/\bFormat-Volume\b/i,
/\b(rd|rmdir)\s+\/s/i,
/\bdel\b.*\/[sq]/i,
/\bgit\s+push\b.*--force/i,
];
pi.on("tool_call", async (event, ctx) => {
if (event.toolName !== "bash" && event.toolName !== "powershell") return undefined;
const comando = String(event.input.command ?? "");
if (!pericolosi.some((p) => p.test(comando))) return undefined;
if (!ctx.hasUI) {
return { block: true, reason: "Comando bloccato: nessuna interfaccia per confermare" };
}
const scelta = await ctx.ui.select(`Comando rischioso:\n\n ${comando}\n\nProcedo?`, ["Sì", "No"]);
return scelta === "Sì" ? undefined : { block: true, reason: "Rifiutato dall'utente" };
});
}L’elenco dei comandi pericolosi contiene modelli di testo per riconoscere, per esempio, la cancellazione ricorsiva di cartelle, la formattazione di un disco e un git push --force, che sovrascrive la cronologia del progetto sul server. Quando uno di questi compare in un comando, Pi ti mostra il comando e aspetta un «Sì» o un «No».
L’esempio ufficiale legge il comando da event.input.command per lo strumento bash. Questo controllo non è una protezione completa: un comando scritto in modo insolito può non essere riconosciuto. Per un isolamento reale il repository propone tre soluzioni: l’estensione Gondolin, che esegue gli strumenti dentro una macchina virtuale Linux leggera, Docker e OpenShell. Per lavorare su codice che non conosci, userei un contenitore Docker.
Sessioni e modalità senza interfaccia
Pi salva ogni conversazione come sessione, e le sessioni hanno la forma di un albero: da qualsiasi punto puoi aprire un ramo alternativo, e tutti i rami restano nello stesso file. Con /tree torni a un punto precedente e riparti da lì. È utile quando l’agente sbaglia strada: invece di spiegargli come rimediare, torni indietro di tre passaggi e riformuli la richiesta, così i tentativi falliti non restano nella conversazione. Il comando pi --continue riprende l’ultima sessione della cartella, mentre /resume te ne fa scegliere un’altra.
Mentre l’agente lavora puoi scrivere altri messaggi. Il tasto Invio manda un messaggio di correzione: Pi lo consegna al modello appena finisce lo strumento in corso e salta quelli ancora in attesa. Alt+Invio manda invece un messaggio che viene letto solo alla fine del lavoro. Il primo serve quando vedi l’agente andare fuori strada, il secondo per aggiungere una richiesta senza interromperlo. Con /export salvi la sessione in un file HTML. Il comando /share la pubblica come gist, cioè una pagina su GitHub raggiungibile con un link. Prima di usarlo rileggi la conversazione, perché percorsi, nomi di progetto e parti di configurazione finiscono online insieme al resto.
Pi funziona anche senza interfaccia. Con pi -p (modalità print) esegue una sola richiesta e stampa la risposta, quindi puoi usarlo dentro uno script:
pi -p "Riassumi @note-riunione.md in cinque punti" > riassunto.txtEsistono poi la modalità JSON, che restituisce l’elenco degli eventi di un’esecuzione in un formato leggibile da altri programmi, la modalità RPC per comandare un processo Pi da un altro programma e l’SDK, un insieme di funzioni per integrare Pi in una tua applicazione TypeScript. Pi è un progetto giovane e la documentazione cambia spesso, quindi controlla la pagina ufficiale prima di iniziare un lavoro importante.
Pi conviene a chi vuole il pieno controllo
Pi è adatto a chi preferisce capire cosa fa il programma invece di avere tutto già pronto. Se vuoi sapere esattamente quali istruzioni riceve il modello, vuoi scegliere il fornitore senza vincoli e non ti spaventa scrivere una ventina di righe di TypeScript per ottenere il comportamento voluto, Pi ti dà un agente che puoi leggere e correggere. L’idea che mi convince di più è che si possa automodificare chiedendo a Pi stesso e ricaricare le modifiche con /reload. La configurazione spetta a te, e l’assenza di una protezione integrata è il limite più serio: se non aggiungi un controllo come quello visto sopra o un contenitore, l’agente può fare tutto ciò che puoi fare tu sul computer. Un utente non esperto deve saperlo prima di usare Pi.
Segui Gomoot
Le nostre recensioni e notizie, dove le cerchi già.
