pi agent toolkit: cinque pacchetti, ricetta SDK, tabella verdetti e checklist del lunedì

TL;DR

• pi è un monorepo con licenza MIT che distribuisce un harness per coding agent come cinque pacchetti separati: un livello API per i modelli, il loop dell'agente, una libreria UI per terminale, il coding agent vero e proprio e un pacchetto di telemetria. Puoi prendere un solo mattone o tutti e cinque.
• La CLI è un coding agent completo fin dal primo giorno: quattro tool predefiniti, cronologia delle sessioni ad albero con fork e resume, un contatore dei costi in tempo reale, e legge l'AGENTS.md o il CLAUDE.md già presente nel tuo repo.
• Il vero valore sta nell'SDK: createAgentSession più un model runtime più un session manager dà un agente funzionante in circa dieci righe di TypeScript, e defineTool aggiunge un tool personalizzato tipizzato senza processo separato né protocollo.
• Il prezzo di questa trasparenza è lavoro: nessuna richiesta di permessi integrata, l'isolamento è a carico tuo, una linea di versioni pre-1.0 (v0.84) e circa cento issue aperte.
• Tieni il tuo harness quotidiano e usa pi come banco di prova che ti mostra cosa nasconde quell'harness. Costruiscici sopra dei prodotti solo se accetti di occuparti tu delle protezioni.

Cosa dicono le fonti

pi è un monorepo: un solo repository che ospita cinque pacchetti pubblicati separatamente, ciascuno per un livello dell'harness s2. pi-ai è l'API unificata verso i provider di modelli (OpenAI, Anthropic, Google e altri dietro un'unica interfaccia), gestisce lo streaming delle risposte, i blocchi di reasoning con i relativi thinking level e la scoperta dinamica dei modelli offerti da ciascun provider s2. pi-agent-core è il loop dell'agente: lo stato della conversazione e il ciclo che invia un messaggio, legge le chiamate ai tool, le esegue e rimanda indietro i risultati s2. pi-tui è una libreria di rendering per terminale con differential rendering, quindi ridisegna solo ciò che è cambiato sullo schermo s2. pi-coding-agent assembla questi mattoni nella CLI che installi, e pi-telemetry ti permette di collegare le tue metriche d'uso senza dipendere da un vendor s3.

I numeri di adozione confermano il design: 92 123 stelle, 11 400 fork e più di 5 700 commit, tutto sotto licenza MIT, che consente uso, modifica e ridistribuzione anche dentro un prodotto commerciale s1. Il ritmo delle release è rimasto costante per tutta l'estate: tre release nelle prime due settimane di agosto, con v0.84.2 pubblicata il 14 s4.

L'installazione è un solo comando, npm install -g --ignore-scripts @earendil-works/pi-coding-agent, e il flag ignore-scripts conta: impedisce alle dipendenze di eseguire i propri script di installazione, una delle superfici d'attacco più sfruttate su npm s3. Una volta collegato a un provider con il comando di login, la barra in basso mostra la cartella corrente, la sessione, i token consumati e il costo in tempo reale, così ogni richiesta viene prezzata mentre parte invece che a fine mese s3.

Le sessioni sono la caratteristica distintiva. Ogni conversazione è salvata come JSONL nella tua cartella home, ordinata per progetto, e la cronologia è un albero e non una linea: fork torna a qualsiasi punto e si dirama, tree naviga tra i rami, e resume riapre qualsiasi sessione passata, anche settimane dopo, perché tutto è archiviato in locale s3. Il modello riceve per impostazione predefinita solo quattro tool: read, write, edit e bash, pochissimi rispetto agli agenti sul mercato, e volutamente s3. La configurazione segue la stessa logica: un settings.json globale nella home, uno per progetto che lo sovrascrive, e un sistema di trust che chiede conferma prima di applicare le impostazioni locali di una cartella aperta per la prima volta. La CLI carica anche l'AGENTS.md o il CLAUDE.md del progetto come contesto, quindi le istruzioni esistenti funzionano senza riscriverle s3.

Lato SDK, createAgentSession prende un ModelRuntime e un SessionManager e restituisce un agente funzionante. Il SessionManager è la scelta di persistenza: in memoria per uno script usa e getta, su disco per ritrovare le conversazioni tra un avvio e l'altro, e le sessioni create dall'SDK condividono la struttura di quelle della CLI s8. L'elenco delle opzioni di createAgentSession permette inoltre di scegliere l'insieme esatto di tool esposti, e perfino l'intero system prompt tramite un ResourceLoader quando vuoi partire da una pagina bianca s8. I tool personalizzati passano da defineTool: un nome, una descrizione, uno schema di parametri tipizzato e una funzione execute, passati a createAgentSession in customTools. Il tool appare al modello esattamente come read o bash, lo schema tipizzato ti dà l'autocompletamento nell'editor e l'agente riceve input già validati. È lo stesso meccanismo di un server MCP, solo che tutto vive nel tuo file, senza processo separato né protocollo in mezzo s8.

La CLI si personalizza con quattro meccanismi, tutti in cartelle del progetto o della home: extension (moduli TypeScript che registrano tool, slash command, scorciatoie da tastiera o elementi UI, caricati all'avvio dalla cartella extensions), skill (pacchetti di capacità secondo lo standard Agent Skills, invocati dal modello o chiamati a mano, quindi le skill esistenti si riusano così come sono), prompt template e temi ricaricati mentre la CLI è in esecuzione s3. Il README riassume la filosofia in una riga: adatta pi ai tuoi workflow e non il contrario, senza fare fork né toccare gli interni s3. Dove i grandi harness incorporano sub-agent, plan mode e permessi nel prodotto, pi li lascia fuori di proposito, da scrivere come extension o installare dalla community s3.

I limiti sono documentati dal progetto stesso. Non ci sono richieste di permessi integrate: per impostazione predefinita l'agente può eseguire un comando bash senza chiedere. La guida ufficiale alla containerizzazione lo ammette e propone tre pattern di isolamento, Docker compreso, ma configurarne uno prima di lasciare l'agente libero su una macchina che conta spetta a te s5. La maturità è l'altro costo: v0.84, non 1.0, circa cento issue aperte e API ancora marcate come sperimentali, come il client di sessione remota aggiunto nelle settimane precedenti s7. Gli stessi mattoni servono già un altro prodotto: pi-chat li applica all'automazione delle conversazioni s6.

Verdetto: tenere, provare o saltare

Da fare lunedì

• Installa la CLI con npm install -g --ignore-scripts @earendil-works/pi-coding-agent, avvia pi, collega un provider con il comando di login e osserva la barra dei costi durante un compito reale.
• Apri un repo che ha già un AGENTS.md o un CLAUDE.md e verifica che pi lo recepisca; confronta le prime risposte dell'agente con il tuo harness abituale sullo stesso prompt.
• Fai una conversazione, poi fork da un nodo precedente e prendi un'altra direzione; elenca ~/.pi/agent/sessions/ per vedere i file JSONL e le loro cartelle di progetto.
• Scrivi un our-agent.ts di venti righe: importa createAgentSession, passa un ModelRuntime e un SessionManager in memoria, chiedi cosa contiene la cartella corrente, eseguilo con npx tsx.
• Aggiungi un defineTool che legge qualcosa dal tuo sistema (un'API interna, una vista di database, un CSV) e passalo in customTools; verifica che l'agente lo chiami da solo davanti a una domanda pertinente.
• Prima di qualsiasi esecuzione con bash abilitato su una macchina a cui tieni, scegli uno dei tre pattern di isolamento della guida alla containerizzazione e configuralo.
• Abbozza una prima extension che intercetta le chiamate bash e chiede conferma per i comandi distruttivi; tienila sotto controllo di versione nella cartella extensions del progetto.
• Dai una scorsa all'elenco delle issue aperte una volta, così sai quali parti si muovono prima di costruirci sopra.

Per approfondire

• Leggi la documentazione dell'SDK per l'elenco completo delle opzioni di createAgentSession: insieme di tool, system prompt via ResourceLoader, session manager s8.
• Studia i tre pattern di isolamento nella guida alla containerizzazione prima di distribuire qualcosa che esegue bash sulla macchina di un utente s5.
• Guarda pi-chat per vedere come gli stessi cinque pacchetti vengono riorganizzati per l'automazione delle conversazioni invece che per il coding s6.
• Sfoglia la cartella packages e leggi pi-agent-core da solo: è la versione leggibile più piccola del loop che ogni harness integrato esegue s2.
• Segui la pagina delle release: da v0.84.0 a v0.84.2 sono uscite in due settimane di agosto, quindi aspettati note di modifica che toccano le extension s4.
• Usa le issue aperte come mappa di ciò che è ancora sperimentale, a partire dal client di sessione remota s7.
• Riusa le skill che hai già scritto per altri tool: la cartella skills di pi segue lo standard Agent Skills s3.

Fonti

• pi: the agent toolkit (repository), Earendil Works. Perché leggerla: il README con l'elenco dei pacchetti, il numero di stelle e fork e la licenza MIT.
• pi monorepo packages, Earendil Works. Perché leggerla: i cinque pacchetti affiancati, il modo più rapido per vedere quale livello possiede ciascuno.
• pi-coding-agent package README, Earendil Works. Perché leggerla: comando di installazione, tool predefiniti, sessioni e i quattro meccanismi di estensione.
• pi releases, Earendil Works. Perché leggerla: il ritmo e il changelog della linea v0.84.
• pi containerization guide (isolation patterns), Earendil Works. Perché leggerla: i tre pattern di isolamento da applicare prima di abilitare bash dove conta.
• pi-chat: the same bricks applied to conversation automation, Earendil Works. Perché leggerla: un secondo prodotto costruito con gli stessi pacchetti, utile per valutarne il riuso.
• pi open issues, Earendil Works. Perché leggerla: l'elenco aggiornato di ciò che è instabile o sperimentale nella versione corrente.
• pi-coding-agent SDK documentation (createAgentSession options), Earendil Works. Perché leggerla: i nomi esatti delle opzioni di createAgentSession, defineTool e dei session manager.

FAQ

pi può sostituire oggi il mio coding agent quotidiano?

Non come sostituto diretto. Esce senza richieste di permessi, l'isolamento è a carico tuo e la linea di versioni è pre-1.0 con circa cento issue aperte. Tieni il tuo harness attuale per il lavoro e usa pi al suo fianco.

Mi serve MCP per dare a pi un tool personalizzato?

No. defineTool prende un nome, una descrizione, uno schema di parametri tipizzato e una funzione execute, e il tool viene passato a createAgentSession in customTools. Si comporta come un tool integrato, senza processo separato né protocollo.

Il mio AGENTS.md, CLAUDE.md e le mie skill funzioneranno?

Sì. La CLI carica automaticamente l'AGENTS.md o il CLAUDE.md del progetto, e la sua cartella skills segue lo standard Agent Skills, quindi le skill esistenti si caricano invariate.

Perché solo quattro tool predefiniti?

read, write, edit e bash sono l'intero set predefinito, molto meno degli agenti sul mercato, e il progetto lo presenta come una scelta. Tutto il resto si aggiunge deliberatamente tramite customTools o un'extension.