Pi: L'Agente di Coding Minimale che Dimostra che Meno È Meglio
Condividi
Iscriviti per una mail al mese con le mie note dal campo.
Uso la tua email solo per la newsletter. Vedi Privacy e Cookie.
Pi: L'Agente di Coding Minimale che Dimostra che Meno È Meglio
C'è una rivoluzione silenziosa in corso nel mondo del coding assistito dall'IA. Mentre l'industria corre a costruire agenti sempre più grandi e complessi — riempiendoli con migliaia di token di system prompt, decine di strumenti specializzati e un'orchestrazione interna opaca — uno sviluppatore ha preso la direzione opposta. E ha cambiato tutto.
Pi è un framework per agenti di coding creato da Mario Zechner, lo sviluppatore dietro il framework di giochi libGDX. Alimenta OpenClaw, il progetto che è passato da zero a oltre 250.000 stelle su GitHub in meno di tre mesi, diventando il repository software più stellato di GitHub — superando persino React.
Questo non è un riassunto. È una guida completa e tecnica a ogni livello di Pi — dalla filosofia alla struttura dei pacchetti, dal loop ReAct alle estensioni auto-estendibili. Se costruisci con agenti IA, questo articolo cambierà il tuo modo di pensarli.
L'Origine: La Frustrazione come Principio di Design
La frustrazione di Mario Zechner era specifica e tecnica. Claude Code — lo strumento che usava quotidianamente — era diventato, nelle sue parole, "un'astronave con l'80% di funzionalità di cui non ho alcun bisogno." I problemi erano concreti:
Instabilità del system prompt: il prompt e le definizioni dei tool cambiavano a ogni release, rompendo silenziosamente workflow accuratamente progettati.
Cecità del context engineering: il framework iniettava contenuto nella finestra di contesto senza mostrarlo nell'interfaccia, rendendo impossibile capire cosa vedesse effettivamente il modello.
Proliferazione dei tool: decine di strumenti sovrapposti competevano per l'attenzione del modello, consumando budget di contesto solo per le descrizioni.
La sua tesi: se riduci un agente di coding al suo minimo assoluto — un system prompt minuscolo, quattro tool e piena trasparenza del contesto — i modelli di frontiera funzioneranno meglio, non peggio. I dati di training contengono già tutto ciò che il modello deve sapere sull'essere un agente di coding.
I risultati gli hanno dato ragione. Pi con Claude Opus ha ottenuto risultati competitivi contro Codex, Cursor e Windsurf su Terminal-Bench 2.0 — con un system prompt sotto i 100 token e esattamente quattro tool.
Pi vs Il Mondo — Posizionamento
Il posizionamento è deliberato. Pi occupa uno spazio che nessun altro strumento rivendica: massima estensibilità con nucleo minimo. Non compete con Claude Code sulle funzionalità — sostiene che la maggior parte di quelle funzionalità non dovrebbe esistere nel framework stesso.
Il grafico sopra racconta la storia visivamente. Quando il tuo system prompt consuma 10.000 token, sono 10.000 token che il modello non può usare per il tuo codice. L'approccio di Pi: dai al modello gli strumenti, dagli il contesto del tuo progetto (AGENTS.md), e lascialo lavorare.
Il Monorepo: Un'Architettura a Livelli
Pi risiede in badlogic/pi-mono — un monorepo TypeScript con npm workspaces e dipendenze a livelli rigorosamente imposte. Il grafo delle dipendenze è un DAG: i pacchetti fondamentali hanno zero dipendenze interne, e ogni livello può dipendere solo verso il basso.
Questa architettura non è casuale. Ogni pacchetto è utilizzabile indipendentemente. Puoi usare pi-ai da solo per l'elaborazione batch di LLM senza alcuna infrastruttura agente. Puoi usare pi-agent-core per incorporare un loop ReAct nella tua applicazione senza la TUI. I livelli sono componibili, non monolitici.
pi-ai: L'API LLM Unificata
La fondazione di tutto. pi-ai mappa oltre 15 provider LLM su un'unica interfaccia unificata — e lo fa riconoscendo una verità fondamentale:
La Superficie dell'API
import { complete, completeStreaming } from "@mariozechner/pi-ai";// Simple completionconst response = await complete({ provider: "anthropic", model: "claude-sonnet-4-6", messages: [{ role: "user", content: "Explain Pi in one sentence." }],});// Streaming with abort supportconst stream = completeStreaming({ provider: "openai", model: "gpt-5", messages, signal: controller.signal, // Abort mid-stream});for await (const chunk of stream) { process.stdout.write(chunk.text);}
Context Handoff — La Funzionalità Killer
La capacità più unica di Pi: le sessioni possono attraversare più provider LLM nella stessa conversazione. Quando passi da Claude a GPT a metà sessione, l'intero contesto — incluse le tracce di ragionamento — viene serializzato e riformattato per il nuovo provider.
// Start with Claude for complex reasoningconst msg1 = await complete({ provider: "anthropic", model: "claude-opus-4-6", messages: conversationHistory,});// Switch to a cheaper model for routine tasksconst msg2 = await complete({ provider: "openai", model: "gpt-4.1-mini", messages: [...conversationHistory, msg1], // Thinking traces auto-converted to tagged text});
Non è un semplice cambio di provider — è una preservazione completa dello stato attraverso formati API fondamentalmente diversi. Nessun'altra libreria LLM unificata implementa questo.
Risultati dei Tool Separati
Un'altra innovazione di Pi: i risultati dei tool possono restituire contenuto separato per l'LLM e l'interfaccia. Il modello riceve un riassunto testuale conciso; la TUI riceve dati strutturati per una visualizzazione ricca:
Ogni sistema agentico — da Claude Code a OpenClaw a Pi — implementa il pattern ReAct (Reasoning + Acting), introdotto da Yao et al. a Princeton/Google nel 2022. L'intuizione chiave: gli LLM funzionano significativamente meglio quando possono ragionare, agire, osservare e ragionare di nuovo, rispetto alle risposte a passaggio singolo.
L'implementazione di Pi è minimale e completamente ispezionabile.
Il Loop, Semplificato
// Pseudocode of Pi's agent loop (actual: ~200 lines of TypeScript)async function agentLoop(messages, tools, model) { while (true) { // 1. REASON: Ask the LLM what to do const response = await complete({ model, messages, tools }); // 2. Check: Is the model done? (text response, no tool calls) if (!response.toolCalls?.length) { return response.text; // Final answer } // 3. ACT: Execute each tool call const toolResults = await Promise.all( response.toolCalls.map(async (call) => { const tool = tools.find((t) => t.name === call.name); const result = await tool.execute(call.arguments); return { toolCallId: call.id, result }; }) ); // 4. OBSERVE: Append results to context messages.push(response); messages.push({ role: "tool", results: toolResults }); // Loop continues — model reasons about results }}
Pipeline di Validazione dei Tool
Ogni chiamata a un tool passa attraverso una rigorosa pipeline di validazione. Gli schemi TypeBox forniscono type safety a compile-time E validazione a runtime con messaggi di errore dettagliati quando gli argomenti del tool falliscono:
Mentre l'agente è in streaming, gli utenti possono iniettare messaggi senza aspettare. Pi supporta due modalità di iniezione fondamentalmente diverse:
Lo Steering interrompe la generazione corrente e reindirizza l'agente. Il Follow-up aspetta che il turno corrente si completi, poi il messaggio viene elaborato nel turno successivo. Questa distinzione è enormemente importante nella pratica — è la differenza tra "fermati, fai quest'altro" e "inoltre, quando hai finito con quello..."
I 4 Tool Fondamentali — E Perché Solo 4
Niente search_codebase. Niente get_git_history. Niente list_directory. Il modello usa bash per qualsiasi cosa che non sia I/O su file. Questo funziona perché:
I modelli di frontiera conoscono già questi tool. Sono stati addestrati estensivamente con RL su scenari di agenti di coding.
Ogni tool aggiuntivo compete per spazio nel contesto. Le descrizioni dei tool sono costose — si trovano in ogni richiesta.
Bash è universale. grep -r, find ., git log — il modello conosce già intimamente questi comandi.
Tool Opzionali in Sola Lettura
Per sessioni di esplorazione sicure (es. onboarding su una nuova codebase), Pi offre la modalità sola lettura:
pi --tools read,grep,find,ls
Questo disabilita write, edit e bash — l'agente può esplorare ma non può modificare nulla. Ideale per la code review o la scoperta dell'architettura.
Sessioni: L'Albero JSONL
Le sessioni di Pi sono memorizzate come file JSONL append-only dove ogni riga è un nodo con un id e un parentId. Questo crea una struttura ad albero che abilita il branching: puoi tornare a qualsiasi punto precedente e continuare, creando un nuovo ramo preservando tutti i rami precedenti nello stesso file.
{"id":"a1","parentId":null,"role":"user","content":"Fix the auth bug"}{"id":"a2","parentId":"a1","role":"assistant","content":"Let me read..."}{"id":"a3","parentId":"a2","role":"tool","results":[...]}{"id":"a4","parentId":"a3","role":"assistant","content":"Found the issue..."}{"id":"b1","parentId":"a2","role":"user","content":"Actually, check tests first"}
Il nodo b1 si dirama da a2, creando una timeline alternativa. Entrambi i percorsi coesistono nello stesso file. L'API SessionManager fornisce operazioni per elencare, creare, riprendere e ramificare sessioni.
Compaction: Lunghezza Illimitata delle Sessioni
Quando una sessione si avvicina all'80% della finestra di contesto (configurabile), Pi attiva la compaction. I messaggi più vecchi vengono sostituiti da un riassunto generato da un modello economico (es. Claude Haiku). Questo consente sessioni di lunghezza illimitata senza degradazione della qualità:
La soglia di compaction è configurabile — e il modello per il riassunto può essere diverso dal modello principale. In pratica, usare Haiku per i riassunti di compaction mentre si esegue Opus per il ragionamento fornisce un'ottima qualità a costo minimo.
Le 4 Modalità Operative
Tutte e quattro le modalità condividono un'unica astrazione: AgentSession. Le modalità differiscono solo nel loro livello di I/O.
Modalità SDK: Come OpenClaw Usa Pi
OpenClaw — l'assistente IA personale con oltre 250K stelle — usa la modalità SDK di Pi. Non lancia Pi come sottoprocesso. Lo importa e lo istanzia direttamente, ottenendo pieno controllo del ciclo di vita:
Questo è il pattern che ha reso possibile OpenClaw. L'"hack del weekend" di Peter Steinberger ha collegato il core agente di Pi a un gateway di messaggistica multi-piattaforma — e il risultato è diventato virale perché il motore agente sottostante (Pi) era abbastanza solido da gestire carichi di lavoro reali e multi-canale.
Il Sistema di Estensioni
Le estensioni sono moduli TypeScript caricati da jiti — un transpiler TypeScript/ESM a runtime che funziona senza fase di build. Questo abilita l'hot-reload: modifica il file .ts, digita /reload, e le modifiche sono attive immediatamente.
Questa è la capacità più radicale di Pi. Poiché le estensioni sono TypeScript caricato senza fase di build, l'agente può scrivere e ricaricare a caldo le proprie estensioni. Il flusso di lavoro:
Descrivi cosa vuoi: "Ho bisogno di un comando /deploy che esegua la nostra pipeline di staging"
Pi scrive l'estensione come file .ts
Digiti /reload
Pi testa il nuovo comando
Se fallisce, Pi legge l'errore, corregge il codice, ricarica e riprova
Armin Ronacher (creatore di Flask e Jinja2) ha descritto questo come "software malleabile come l'argilla." Tutte le sue estensioni Pi — /answer, /todos, /review, /files — sono state scritte da Pi stesso, non da Armin. Lui ha descritto i requisiti, ha indicato all'agente degli esempi, e Pi le ha implementate autonomamente.
Il System Prompt: ~100 Token
Questo è l'effettivo system prompt di Pi, riprodotto dal codice sorgente. Confrontalo con i ~10.000 token di Claude Code:
You are an AI coding assistant. You help users with software engineering tasks.
Use the provided tools to accomplish tasks.
Tutto qui. Il resto del budget di contesto è allocato a:
La gerarchia si carica in quest'ordine:
System prompt (~100 token)
Definizioni dei tool (~900 token)
File AGENTS.md (contesto specifico del progetto, controllato dall'utente)
Skill (disclosure progressiva — caricati su richiesta)
Cronologia della conversazione (la maggior parte del contesto)
L'utente controlla la maggior parte del budget di contesto attraverso AGENTS.md. Questo è l'opposto dell'approccio di Claude Code, dove il framework controlla la maggior parte del contesto e l'utente ottiene ciò che rimane.
Skill: Lo Standard agentskills.io
Pi implementa agentskills.io — uno standard aperto per pacchetti di skill portabili. Le skill scritte per Pi funzionano identicamente in Claude Code, Codex CLI, Amp e Droid.
Formato SKILL.md
---name: code-reviewversion: 1.0.0description: Automated code review with style checkstriggers: - /review - "review this"---# Code Review SkillYou are a code review assistant. When activated:1. Read the staged git diff2. Check for: - Security vulnerabilities - Performance issues - Style violations - Missing error handling3. Provide actionable feedback with line references
Le skill utilizzano la disclosure progressiva: il loro contenuto completo viene caricato nel contesto solo quando attivate, non all'avvio della sessione. Questo mantiene il contesto base snello rendendo disponibili funzionalità approfondite su richiesta.
Repository Ufficiali delle Skill
Pattern Agentici: 5 Modi di Usare Pi
Pattern 1: ReAct (Predefinito)
Il comportamento predefinito. Non serve configurazione — il modello decide quando chiamare i tool in base al contesto:
pi "Fix the failing tests in src/auth/"
Pattern 2: Plan-and-Execute
Per task multi-step ben definiti, genera prima un piano, poi esegui. La ricerca mostra un tasso di completamento del 92% e un velocizzazione di 3.6x rispetto al ReAct sequenziale:
pi "Use /plan to refactor the payment module to use Stripe v3"
Usando sottoprocessi pi --print o il pacchetto nicobailon/pi-subagents per l'esecuzione parallela:
# agents/security-reviewer.md---name: security-reviewermodel: claude-sonnet-4-6tools: [read, grep, find]---You are a security specialist. Review code for OWASP Top 10 vulnerabilities.
Pattern 4: Reflection
Fai revisionare l'output dell'agente primario da un agente specialista prima di presentarlo:
pi "Implement the feature, then use /reflect to review your own work"
Pattern 5: Caricamento Dinamico dei Tool
Quando hai oltre 50 tool, caricali progressivamente per evitare il degrado dell'accuratezza:
api.on("resources_discover", async () => { // Only load tools relevant to current context const packageJson = await readFile("package.json"); if (packageJson.includes("prisma")) { api.addTool(prismaQueryTool); }});
La Storia di OpenClaw: Da Hack del Weekend a 250K Stelle
OpenClaw è nato come un "hack del weekend" dello sviluppatore austriaco Peter Steinberger. Il concetto: un assistente IA personale che gira sui tuoi dispositivi e risponde sui canali che già usi — WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, IRC, Microsoft Teams, Matrix, LINE e altri.
L'architettura è diretta: OpenClaw è un gateway di messaggistica che usa l'SDK createAgentSession() di Pi per incorporare un agente di coding completo. Ogni canale ottiene la propria sessione isolata. Il sandboxing Docker garantisce che il codice dell'agente giri in sicurezza. Gli eventi schedulati abilitano trigger simili a cron.
Perché Pi Ha Reso Possibile OpenClaw
Modalità SDK: Pi si incorpora come libreria, non come sottoprocesso — pieno controllo del ciclo di vita
Agnosticismo del provider: gli utenti scelgono il loro LLM (Claude, GPT, Gemini, modelli locali via Ollama)
Sistema di estensioni: OpenClaw aggiunge estensioni personalizzate per funzionalità specifiche della piattaforma
Persistenza delle sessioni: il formato ad albero JSONL fa sì che le conversazioni sopravvivano ai riavvii
Footprint minimale: il core minuscolo di Pi significa avvio rapido e basso consumo di memoria
L'Integrazione con Ollama
A marzo 2026, Ollama ha ufficialmente aggiunto ollama launch pi alla sua CLI — rendendo Pi il primo framework agentico accessibile con un singolo comando. Combinato con Kimi K2.5 (un modello MoE da 1 trilione di parametri), questo significa:
ollama launch pi --model kimi-k2.5:cloud
Un agente di coding completo, alimentato da un modello da un trilione di parametri, a un costo 9 volte inferiore rispetto a Claude Opus. $0,60 per milione di token di input. $3,00 per milione di token di output.
La TUI: Retained Mode vs Immediate Mode
La terminal UI di Pi (pi-tui) fa una scelta architetturale fondamentale che differisce da ogni altro agente di coding:
L'approccio retained mode significa che la TUI di Pi non sfarfalla mai. I componenti persistono tra i frame, memorizzano in cache il loro output renderizzato e ri-renderizzano solo ciò che è cambiato. È lo stesso modello di rendering differenziale usato da React — ma per il terminale.
Le estensioni hanno pieno accesso al sistema di componenti. Puoi costruire interfacce interattive — barre di progresso, tabelle, menu di selezione, blocchi di codice con syntax highlighting — che si integrano perfettamente con l'output dell'agente.
Le 7 Modalità di Fallimento degli Agenti (e le Soluzioni di Pi)
Economia del Contesto: Perché Ogni Token Conta
Il grafico illustra perché l'approccio minimale di Pi vince economicamente. Quando il tuo framework consuma 15.000 token prima del primo messaggio dell'utente, stai pagando quel sovraccarico su ogni singola chiamata API. Su una sessione lunga con centinaia di turni, il costo cumulativo di un system prompt gonfio è enorme.
L'approccio di Pi: ~1.000 token per system prompt + tool. Il budget rimanente è tuo.
Come Iniziare
Step 1: Installazione
npm install -g @mariozechner/pi-coding-agent# orollama launch pi
Step 2: Configura un Provider
# Anthropic (recommended)export ANTHROPIC_API_KEY=sk-ant-...# OpenAIexport OPENAI_API_KEY=sk-...# Local models via Ollama# No API key needed — Pi auto-detects local Ollama
Step 3: Crea AGENTS.md
# My Project## Tech Stack- Next.js 15, TypeScript, Tailwind CSS- PostgreSQL with Drizzle ORM- Deployed on Vercel## Conventions- Use conventional commits- Tests required for all new features- No direct database queries — use the ORM layer
Step 4: Esegui
# Interactive mode (default)pi# With a specific modelpi --model claude-opus-4-6# Print mode for scriptingpi --print "Generate a migration for adding user roles"# Read-only explorationpi --tools read,grep,find,ls "Explain the auth flow"
Step 5: Costruisci la Tua Prima Estensione
// .pi/extensions/hello.tsexport default function (api) { api.addSlashCommand({ name: "hello", description: "A warm greeting", execute: async () => "Hello from my first Pi extension!", });}
Digita /reload in Pi, poi /hello. La tua estensione è attiva.
Perché l'Open Source, Ridotto all'Essenziale, Vince
La lezione di Pi non è che il minimalismo è sempre meglio. È che il minimalismo nei posti giusti — il system prompt, il set di tool, il loop principale — crea spazio per il massimalismo dove conta: nel controllo dell'utente su contesto, estensioni e workflow.
Claude Code è un prodotto eccellente. Cursor è un prodotto eccellente. Ma sono prodotti — progettati per l'utente medio, ottimizzati per il caso comune. Pi è un toolkit — progettato per sviluppatori che vogliono capire e controllare ogni token che entra nella finestra di contesto del loro agente.
Le prove parlano da sole:
31.600+ stelle su GitHub sul repository core
250.000+ stelle su OpenClaw (costruito sull'SDK di Pi)
184 release in sviluppo attivo
Integrazione Ollama che lo rende installabile con un singolo comando
agentskills.io che stabilisce uno standard di skill cross-agente
Risultati competitivi nei benchmark con una frazione della complessità
La prossima volta che combatti con un agente di coding che fa qualcosa di inaspettato — inietta contenuto che non puoi vedere, chiama tool che non hai chiesto, consuma contesto su funzionalità che non usi — ricorda che c'è un'alternativa. Una che si fida del modello, si fida dello sviluppatore, e si toglie di mezzo.
Quell'alternativa è Pi. E sta dimostrando che nell'era degli agenti IA, il miglior framework è quello che quasi non esiste.
Pi è open source sotto licenza MIT. Repository: badlogic/pi-mono. Sito ufficiale: pi.dev.
