Pi Coding Agent: uno stack minimale ed estensibile

Pi è un framework per coding agent costruito attorno a un system prompt contenuto, pochi strumenti predefiniti e un contesto di progetto visibile. Non impone un flusso di lavoro unico: offre un runtime compatto che chi sviluppa può estendere.

L'ha creato Mario Zechner, sviluppatore di libGDX, dopo aver trovato sempre più difficile capire e controllare il coding agent che usava. Pi è poi diventato il motore di OpenClaw, una verifica molto più esposta del suo design rispetto al solo terminale.

L'articolo fotografa il progetto al 27 aprile 2026. L'ultima release su GitHub era v0.70.2, pubblicata il 24 aprile, e il repository mostrava circa 40.800 stelle. Questi numeri invecchieranno; l'architettura è il dato più interessante.

Un nucleo piccolo, con più punti di controllo

Pi parte da un harness da terminale ristretto e affida la personalizzazione a file di progetto, skill, estensioni TypeScript e pacchetti. Supporta più provider, sessioni ramificate, compattazione e uso da terminale o programmatico, ma queste capacità restano separate dal default di quattro tool. La complessità non scompare: si sposta in componenti selezionabili e versionabili.

| Livello | Funzione | | --------------------------------- | --------------------------------------------------------------- | | AGENTS.md | Comandi, architettura, regole e azioni vietate nel progetto | | .pi/settings.json | Modelli, ragionamento, pacchetti, skill, compaction e tentativi | | .pi/extensions/ | Tool TypeScript, hook, comandi, permessi e componenti UI | | .pi/skills/ o .agents/skills/ | Procedure dettagliate caricate su richiesta | | .pi/prompts/ | Template di prompt riutilizzabili | | models.json | Provider personalizzati, locali e compatibili con OpenAI |

Perché Zechner ha ridotto l'harness

Zechner ha definito Claude Code «un'astronave di cui non uso l'80% delle funzioni». Le sue obiezioni erano tecniche: system prompt e definizioni dei tool cambiavano tra le versioni, le aggiunte nascoste rendevano difficile ricostruire ciò che il modello vedeva e strumenti sovrapposti consumavano contesto a ogni richiesta.

Pi parte dunque da read, bash, edit e write. La shell copre ricerca, elenchi di directory e cronologia Git senza dedicare un tool a ciascuna operazione. Per le analisi sono disponibili strumenti opzionali in sola lettura, senza modifica dei file né esecuzione della shell.

La scelta si regge su due ipotesi. I modelli addestrati alla programmazione conoscono bene le normali utility da terminale, mentre ogni tool visibile nello schema occupa spazio e attenzione a ogni richiesta. Un catalogo più ampio può rendere elegante la singola operazione, ma obbliga il modello a distinguere descrizioni spesso sovrapposte. Pi usa la shell come interfaccia comune e lascia gli strumenti specialistici alle estensioni. bash conserva però ampi poteri: pochi tool non significano pochi permessi.

Nel novembre 2025 Zechner scrisse che il system prompt e le definizioni dei tool stavano allora sotto i 1.000 token, contro più di 10.000 per il solo system prompt di Claude Code. È una misura legata alla versione. Nella v0.70.2 il prompt generato comprendeva anche lista dinamica dei tool, linee guida operative, percorsi della documentazione, data e directory di lavoro; contesto di progetto e skill aggiungono altro testo. Resta valida la scelta di un default ristretto e visibile, non un conteggio immutabile.

In un'esecuzione di Terminal-Bench 2.0 con cinque prove per task, pubblicata nel dicembre 2025, Pi con Claude Opus 4.5 ottenne 0,4787. Zechner la confrontò con le voci allora presenti per Codex, Cursor e Windsurf, ciascuna con il proprio modello. Era un confronto con la classifica di quel momento, non un esperimento controllato sul solo harness.

Un monorepo diviso per livelli

Pi vive nel monorepo TypeScript badlogic/pi-mono. Le dipendenze interne formano un grafo aciclico: i pacchetti di base non dipendono dall'interfaccia né dall'applicazione completa.

La separazione consente di usare soltanto una parte dello stack. pi-ai funziona come libreria multi-provider senza alcun agente; pi-agent-core incorpora il loop in un'altra applicazione senza la TUI. I livelli superiori aggiungono sessioni, strumenti, estensioni e presentazione.

Anche la TUI è un pacchetto riutilizzabile. Adotta un rendering retained mode: i componenti persistono tra i frame, conservano l'output e aggiornano soltanto le regioni cambiate. Si riduce lo sfarfallio e le estensioni possono mostrare tabelle, selettori, avanzamento o codice evidenziato nella stessa interfaccia. La presentazione rimane così separata dal loop dell'agente.

Un'interfaccia comune per i modelli

pi-ai riconduce i provider supportati a quattro famiglie principali: compatibili OpenAI, Anthropic, Google Gemini e Amazon Bedrock. È una strategia d'implementazione, non l'affermazione che i provider si comportino allo stesso modo.

Il passaggio è importante perché gli schemi delle API differiscono. Pi serializza la conversazione, la converte e conserva le tracce di ragionamento dove possibile. Anche i risultati dei tool possono avere due forme: testo sintetico per il modello e dati strutturati per la TUI. I dettagli di presentazione non entrano così nel contesto del modello.

Un loop ispezionabile

pi-agent-core realizza un ciclo di tipo ReAct: chiede una risposta al modello, esegue le chiamate ai tool, aggiunge le osservazioni e ripete finché arriva una risposta finale. Gli argomenti dei tool usano schemi TypeBox, validi sia per i tipi TypeScript sia per i controlli a runtime. Il loop è abbastanza piccolo da essere letto; il prodotto completo contiene naturalmente altro codice per provider, sessioni, errori e interfaccia.

Un messaggio inviato durante l'esecuzione può interrompere e reindirizzare la generazione, oppure attendere la conclusione del turno corrente. Distinguere steering e follow-up evita che ogni nuovo input venga trattato sempre come uno stop urgente o sempre come una richiesta passiva.

Le sessioni sono alberi, non trascrizioni lineari

Pi salva le sessioni come nodi JSONL append-only con id e parentId. Tornare a un nodo precedente apre un altro ramo senza cancellare il percorso già compiuto. Si possono così provare alternative senza copiare l'intera conversazione.

Quando il contesto si riempie, la compaction sostituisce i messaggi più vecchi con un riepilogo. Soglia e modello di sintesi sono configurabili: un modello economico può riassumere e uno più forte svolgere il compito principale. La trascrizione completa rimane su disco, ma il riepilogo attivo perde inevitabilmente dettagli. La compaction prolunga una sessione, non crea memoria illimitata.

Le quattro modalità condividono l'astrazione AgentSession. Quella interattiva offre la TUI, print e JSON servono gli script, RPC espone un confine di processo e l'SDK incorpora direttamente l'agente.

Le estensioni contengono ciò che Pi lascia fuori

Le estensioni sono moduli TypeScript caricati tramite jiti. Non richiedono una compilazione separata e possono essere ricaricati durante la sessione. Registrano comandi, tool, scorciatoie, eventi, provider, componenti UI e controlli sull'accesso a file e shell.

Pi può quindi scrivere un'estensione partendo dai requisiti dell'utente e ricaricarla per provarla. Armin Ronacher, creatore di Flask e Jinja2, ha parlato di software «malleabile come argilla». Racconta che Pi ha implementato le sue estensioni /answer, /todos, /review e /files usando requisiti ed esempi. La comodità non cambia la natura del risultato: un'estensione generata è codice eseguibile e va revisionata.

Pi non include una modalità di pianificazione né sub-agent nativi. Il piano può vivere in un file o in un'estensione; il parallelismo può arrivare da sottoprocessi, pannelli di terminale o pacchetti. È una scelta sul confine dell'API, non l'impossibilità di adottare quei flussi.

Le skill sono un'estensione più leggera. Pi implementa il formato agentskills.io e può scoprire directory globali o di progetto, comprese quelle di Claude Code o Codex indicate nelle impostazioni. All'avvio espone i metadati; le istruzioni complete entrano nel contesto solo al richiamo. La portabilità effettiva dipende comunque dagli strumenti e dal comportamento dell'host.

I pacchetti distribuiscono insieme queste risorse. L'ecosistema comprende skill riutilizzabili, tool di Ollama per ricerca e lettura del web e un ciclo di ricerca automatica che ottimizza misure come tempo dei test o dimensione del bundle. Le risorse locali viaggiano con il repository; quelle globali seguono l'utente. La provenienza conta: una skill può limitarsi alle istruzioni, mentre un'estensione o un pacchetto può eseguire codice e installare dipendenze.

Lo stesso modello spiega la varietà dei flussi possibili. Il default resta un ciclo ReAct, ma un file può contenere un piano approvato, un secondo agente può girare come sottoprocesso e un hook può caricare un tool solo nei repository che lo richiedono. Sono composizioni dei confini esistenti, non modalità battezzate e inserite nel core.

OpenClaw ha messo alla prova l'SDK

Peter Steinberger iniziò OpenClaw come progetto di un fine settimana: un assistente personale raggiungibile da WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Microsoft Teams, Matrix e altri canali. Incorpora Pi con createAgentSession() invece di avviarlo come sottoprocesso opaco. Sessioni per canale, scelta del provider, persistenza ed estensioni si appoggiano alla stessa astrazione SDK.

La crescita di OpenClaw non dimostra che un harness minimale sia migliore in ogni compito. Mostra però che il nucleo di Pi può diventare infrastruttura dentro un'applicazione molto più grande. L'architettura assegna sessioni isolate ai canali, conserva le conversazioni dopo i riavvii, aggiunge eventi pianificati e usa Docker per isolare i carichi di lavoro. L'indipendenza dai provider consente di scegliere modelli remoti o locali. L'integrazione di Ollama offre un secondo esempio: configura Pi per i modelli locali e aggiunge tool separati per la ricerca web senza cambiare il core.

Il contesto è la risorsa scarsa

L'architettura torna sempre alla gestione del contesto. Definizioni dei tool e istruzioni permanenti accompagnano ogni richiesta successiva; file e memoria esterna incidono sul risultato soltanto quando l'harness li recupera. Caricamento progressivo delle skill, output distinti per modello e interfaccia, compaction e passaggio tra provider rispondono in modi diversi allo stesso limite.

Un contesto più corto non è sempre migliore. Un'istruzione omessa può costare più di quanto risparmi se il modello ripete il lavoro o ignora una regola del progetto. Un riepilogo scadente può perdere il dettaglio necessario alla decisione successiva. Pi rende visibili queste scelte: si può distinguere ciò che è permanente, ciò che arriva su richiesta e ciò che è stato compresso, quindi misurare il compromesso sul proprio carico di lavoro.

Per questo conta anche la trascrizione append-only. Il contesto attivo è un insieme di lavoro temporaneo; il file della sessione contiene una storia più ampia. I rami proteggono percorsi alternativi, mentre la compaction sceglie quale parte resta subito disponibile. Nessuno dei due meccanismi trasforma le informazioni archiviate in comprensione: la qualità del recupero e del riepilogo resta decisiva.

Il compromesso

Pi sposta la complessità dai comportamenti fissi del prodotto a configurazione e codice controllati dall'utente. La tracciabilità migliora: le istruzioni sono file, le skill si caricano su richiesta, il routing è esplicito e le estensioni si possono esaminare. Aumenta però il lavoro per chi sviluppa. Un gruppo deve scegliere, revisionare e mantenere questi livelli anziché affidarsi ai default di un fornitore.

Quattro tool non eliminano gli errori. Il modello può usare male la shell, perdere dettagli nella compaction, seguire istruzioni di progetto sbagliate o scrivere codice errato. Estensioni e pacchetti allargano il confine di fiducia; una sessione può inoltre cambiare comportamento dopo il passaggio a un altro provider. L'ispezionabilità aiuta a trovare il problema, non lo risolve da sola.

Pi è soprattutto uno stack componibile e incorporabile, più che una versione leggera di un assistente commerciale. La sua proposta è concreta: se un software può modificare un repository ed eseguire comandi, istruzioni e meccanismi che lo guidano dovrebbero restare visibili.

Stato: dettagli del progetto e delle release verificati sulle fonti elencate sotto il 27 aprile 2026.

Pi è open source con licenza MIT. Repository: badlogic/pi-mono. Sito ufficiale: pi.dev.

OpenClaw: openclaw/openclaw. Analisi di Armin Ronacher: Pi: The Minimal Agent Within OpenClaw.

Fonti principali dell'aggiornamento: sito ufficiale di Pi, README di Pi, documentazione su estensioni, skill, pacchetti e impostazioni, release GitHub v0.70.2, v0.70.1 e v0.70.0, e integrazione di Ollama.

Terminal-Bench e snapshot storici: articolo di Zechner del novembre 2025, risultato inviato a Terminal-Bench e snapshot archiviati di OpenClaw del 30 gennaio, 2 febbraio, 1° marzo e 14 marzo 2026.