AIDiveIl tuo agente è una scatola nera
Claude Code, Codex e Gemini CLI sono agent harness progettati da qualcun altro — e se passi la giornata lavorativa dentro uno di questi, convivi con quella scelta di design. Vuoi cambiare un comportamento, aggiungere uno strumento, stringere una regola di permesso? Aspetti che il vendor si decida a rilasciarlo. Non sai cosa c'è nel system prompt, non vedi il loop che esegue gli strumenti, e non puoi cambiare nulla di tutto ciò, anche se questi strumenti sono ormai la postazione principale di migliaia di sviluppatori.
Un progetto open source prende l'approccio opposto: pi, un toolkit che fornisce i pezzi di ricambio per montare il proprio agente, dal connettore al modello fino all'interfaccia. Ha raccolto 92.000 stelle su GitHub nel suo primo anno e rilascia quasi ogni settimana. Questo articolo copre cosa mette davvero pi nella scatola, come costruire il proprio agente con il suo SDK, e un verdetto onesto contro gli harness già pronti.
Cos'è davvero un harness
Un harness è tutta la macchina intorno a un modello linguistico che lo trasforma in un agente funzionante. Un modello da solo sa fare una cosa sola: leggere testo e produrre testo. Non legge i tuoi file, non esegue un solo comando, e non ricorda niente da una sessione all'altra. Tutto il resto è l'harness — il system prompt che inquadra il modello, gli strumenti a cui ha accesso, il loop che esegue le chiamate agli strumenti e restituisce i risultati, e l'interfaccia nel tuo terminale.
L'harness decide anche i dettagli che fanno differenza ogni giorno: come si comprime la cronologia quando il contesto trabocca, come un errore di uno strumento torna al modello, cosa viene loggato e cosa no. Claude Code è un harness. Anche Codex. Quando un agente ti impressiona, buona parte del merito va a quella macchina, non al modello — collega lo stesso modello a due harness diversi e ottieni due agenti che non sono allo stesso livello.
pi, creato da Earendil Works, taglia quella macchina in blocchi riutilizzabili. Puoi usare il suo coding agent così com'è, o prendere i blocchi uno a uno e costruire il tuo. È la seconda opzione quella che ci interessa.
Dentro il toolkit pi
pi è un monorepo — un unico repository che ospita cinque pacchetti pubblicati separatamente — e ogni pacchetto copre un piano dell'harness:
| Pacchetto | Cosa fa |
|---|---|
| pi-ai | API unificata verso OpenAI, Anthropic, Google e il resto: streaming delle risposte, blocchi di reasoning con i loro livelli, scoperta dinamica dei modelli di ogni provider. Cambi laboratorio solo cambiando un argomento. |
| pi-agent-core | Il loop dell'agente stesso: lo stato della conversazione, più il ciclo che invia il messaggio, legge le chiamate agli strumenti, le esegue e restituisce i risultati finché il compito è finito. I casi complicati — uno strumento che fallisce, una risposta tagliata a metà, chiamate parallele — sono già gestiti. |
| pi-tui | Libreria di rendering del terminale con rendering differenziale: ridisegna solo ciò che cambia sullo schermo. |
| pi-coding-agent | Il coding agent completo, montato dai blocchi sopra — prova che il toolkit basta per costruire un prodotto finito. |
| pi-telemetry | Collega le tue metriche d'uso senza dipendere da un vendor. |
Il loop dell'agente è esattamente il pezzo che riscriveresti male da zero; scriverlo bene richiede settimane, e tu lo ottieni con un import. Il team applica la stessa ricetta altrove: un repository a parte, pi-chat, riusa gli stessi blocchi per automatizzare conversazioni.
I numeri dicono che la formula funziona:
| Metrica | Valore |
|---|---|
| Stelle su GitHub | 92.123 |
| Fork | 11.400 |
| Commit | 5.700+ |
| Licenza | MIT |
| Release nelle prime due settimane di agosto 2026 | 3 (v0.84.2 uscita il 14 agosto) |
La licenza MIT significa che puoi usare, modificare e ridistribuire pi senza restrizioni, anche in un prodotto commerciale. pi non è solo un altro framework: è un harness completo consegnato a pezzi, mantenuto con un ritmo costante.
La CLI in pratica
La CLI di pi è il coding agent già montato che ottieni prima ancora di toccare del codice, ed è da qui che inizierai. L'installazione è una riga, e il flag --ignore-scripts non è un dettaglio: impedisce alle tue dipendenze di eseguire i loro script d'installazione, una delle superfici d'attacco più sfruttate su npm. Lancia pi, collega il tuo provider col comando login, e hai un coding agent proprio qui nel tuo terminale. La barra di stato mostra la cartella corrente, la sessione, i token consumati e il costo in tempo reale — vedi ogni richiesta con il prezzo nel momento in cui parte, invece di scoprire la fattura a fine mese.
I comandi slash coprono la quotidianità: model per cambiare modello al volo, compact per riassumere la cronologia quando il contesto si gonfia, export per estrarre la conversazione, settings per il resto. Un file markdown nella cartella prompts diventa un comando che attivi digitando il nome.
La vera firma di pi è la gestione delle sessioni. Ogni conversazione è salvata come JSONL nella tua home, ordinata per progetto — e la cronologia è in realtà un albero, non una linea. Puoi tornare a qualsiasi punto di una conversazione e prendere un'altra strada col comando fork, poi muoverti tra i rami con tree. Un prompt fallito ora non ti costa più nulla: torni al nodo precedente e riprovi, senza perdere l'altro ramo. Dato che tutto è salvato in locale, resume ti riporta in qualsiasi sessione passata, anche settimane dopo. Né Claude Code né Codex offrono una navigazione della cronologia in questa forma.
Di default, il modello riceve solo quattro strumenti: read, write, edit e bash. Pochissimo rispetto agli agenti sul mercato, ed è deliberato (ci torniamo più avanti). La configurazione segue la stessa logica: un file di impostazioni globale nella tua home, uno per progetto che lo sovrascrive, e un sistema di fiducia che chiede prima di applicare le impostazioni locali di una cartella aperta per la prima volta. Se migri, pi carica automaticamente i tuoi file AGENTS.md o CLAUDE.md esistenti come contesto, quindi le istruzioni esistenti funzionano senza riscriverle.
Costruiamo il nostro agente
Costruire un agente con l'SDK di pi inizia con un solo import: createAgentSession, a cui passi un model runtime e un session manager, restituisce un agente funzionante. Il session manager è la scelta di persistenza — in memoria per uno script usa-e-getta, o su disco per ritrovare le tue conversazioni da un run all'altro.
L'abbiamo provato su un progetto locale. Il nostro script chiede cosa c'è nella cartella corrente; l'agente chiama il suo strumento read, legge la cartella e risponde. Quello è il loop completo, scritto da noi, in circa dieci righe di TypeScript. Le sessioni create dall'SDK hanno la stessa struttura ad albero della CLI — ogni messaggio è legato al suo genitore — quindi la ramificazione della cronologia funziona anche nel tuo codice.
Gli strumenti custom sono dove diventa interessante. defineTool prende un nome, una descrizione, uno schema di parametri tipizzato e una funzione execute, e il tuo strumento appare al modello esattamente come read o bash. Ne abbiamo scritto uno che interroga la lista video del canale, passato in customTools, e l'agente l'ha chiamato da solo dalla prima domanda pertinente. È fondamentalmente lo stesso meccanismo di un server MCP, tranne che tutto vive nel tuo file — senza processo separato, senza protocollo in mezzo. Dato che lo schema dei parametri è tipizzato, il tuo editor completa automaticamente gli argomenti e l'agente riceve input già validati.
Controlli anche il modello, il livello di ragionamento (da spento a massimo), la lista esatta di strumenti che il modello vede, e persino l'intero system prompt tramite un resource loader se vuoi ripartire da una pagina bianca. Per la visualizzazione, session.subscribe ti dà ogni evento — testo in streaming, chiamate agli strumenti, errori — da reindirizzare dove vuoi: un terminale, un bot di messaggistica, o una pipeline CI che commenta le tue pull request. In un pomeriggio passi da usare un agente ad averne scritto uno, e sai finalmente cosa succede a ogni giro del loop.
Estenderlo senza forkare
La CLI di pi si personalizza con quattro meccanismi, tutti in cartelle normali del tuo progetto o della tua home:
- Extensions — moduli TypeScript che registrano strumenti, comandi slash, scorciatoie o elementi UI. Metti il file nella cartella extensions e si carica all'avvio. È lì che scriveresti una guardia dei permessi, per esempio: un'estensione che intercetta i comandi bash e chiede conferma prima di quelli pericolosi.
- Skills — pacchetti di capacità che seguono lo standard Agent Skills, lo stesso reso popolare da Anthropic, quindi le tue skill esistenti sono riutilizzabili così come sono.
- Prompts — prompt riutilizzabili come semplici file markdown.
- Themes — si ricaricano a caldo mentre la CLI gira.
Tutto si installa come un pacchetto qualsiasi: pi install prende un pacchetto npm o un repository git, e un comando aggiorna tutto. I doc riassumono la filosofia in una frase: adatta pi ai tuoi flussi, non il contrario, senza fork né patch interne.
È l'opposto dei grandi harness. Dove Claude Code integra sub-agent, plan mode e permessi dentro il prodotto, pi li lascia fuori deliberatamente, da costruire come estensione o installare dalla community. La scommessa è chiara: un core minimo che si muove a malapena, e tutta la personalizzazione vive dalla tua parte, in file che versioni insieme al progetto.
Il vero limite
La trasparenza di pi si paga con il lavoro, e quel costo ha tre parti.
Prima i guardrail: di default non ci sono prompt di permesso integrati, quindi l'agente può eseguire un comando bash senza chiederti nulla. I doc ufficiali lo ammettono e propongono tre pattern di isolamento, Docker incluso — ma metterli in pratica prima di lasciare l'agente su una macchina importante spetta a te.
Poi la maturità: questo è v0.84, non 1.0, con circa cento issue aperte e alcune API ancora segnate come sperimentali, come il client di sessione remota aggiunto nelle ultime settimane. Ciò che funziona oggi può rompersi nella prossima release; è il prezzo normale di un progetto che va così veloce.
E infine, il tempo. Ogni comodità che Claude Code ti dà di serie — plan mode, sub-agent, permessi granulari — qui diventa un progetto che costruisci tu stesso, o un pacchetto community che insegui sperando che resti mantenuto. L'ecosistema di estensioni ha solo un anno: troverai più buchi da riempire che pacchetti già pronti. Perfino l'installazione ti ha insegnato il livello di attenzione richiesto, col suo flag --ignore-scripts, e dovrai mantenerlo lungo tutta la catena. Se il tuo obiettivo è spedire codice stasera, pi prima ti rallenterà, poi ti accelererà — non sostituire il tuo harness principale questa settimana solo per questo video.
Per chi è davvero pi
pi è per gli sviluppatori che costruiscono prodotti con agenti, non solo con uno. Per loro è probabilmente il miglior investimento di apprendimento del momento: installa la CLI, scrivi un agente di venti righe con l'SDK, e dagli uno strumento tuo. Fallo e capirai Claude Code meglio della maggior parte degli utenti.
Se vuoi solo un assistente produttivo oggi, resta sul tuo harness integrato e torna quando 1.0 avrà i guardrail: il valore di pi sta nel capire e controllare, non nel comfort immediato. Tra i due c'è una via di mezzo senza rischi — tieni Claude Code per il lavoro, e usa pi come banco di prova per capire cosa nasconde il tuo strumento principale.
La cosa che portiamo a casa è che gli harness non sono più scatole nere: i pezzi sono sul tavolo, documentati, licenza MIT. La prossima volta che un agente ti impressiona o ti irrita, saprai esattamente quale pezzo guardare.
