Pi Coding Agent: lo stack minimale ed estensibile per sviluppatori seri

I migliori coding agent del 2026 non sono chatbot un po' più bravi con accesso ai file. Sono ambienti di lavoro programmabili: un po' terminale, un po' model router, un po' workflow engine, un po' sistema di memoria. Quasi tutti i tool nascondono questa macchina dietro un prodotto confezionato. Pi scommette al contrario: tiene il core abbastanza piccolo da poterlo capire per intero, e lascia a te il controllo del workflow.

Pi è un framework per agenti di coding creato da Mario Zechner, lo stesso sviluppatore del framework di giochi libGDX. È il motore di OpenClaw, il progetto passato da zero a oltre 250.000 stelle su GitHub in meno di tre mesi — oggi il repository software più stellato della piattaforma, davanti persino a React.

Questa è una guida tecnica a Pi così com'è adesso: il loop agentico minimale, il sistema di package, le skill, le estensioni TypeScript, i settings locali al progetto, l'integrazione Ollama, il supporto DeepSeek, i flussi di login OAuth e API key, i controlli sulla telemetry e una configurazione seria — per chi vuole un agente da ispezionare, non un prodotto da subire.

Aggiornamento di aprile 2026: Pi è diventato un kernel agentico programmabile

Aggiornato il 27 aprile 2026. La novità vera rispetto alla prima versione di questo articolo è che Pi non è più "una piccola alternativa a Claude Code". La documentazione ufficiale ormai lo descrive come un harness terminale minimale da adattare con estensioni TypeScript, skill, prompt template, temi e Pi package installabili. Il sito pubblico racconta la stessa traiettoria: oltre 15 provider, centinaia di modelli, autenticazione via API key o OAuth, sessioni ad albero, caricamento di AGENTS.md, compaction personalizzabile, installazione di package e quattro modalità operative — interactive, print/JSON, RPC e SDK.

L'ultima release GitHub visibile al momento di questo aggiornamento è la v0.70.2 del 24 aprile 2026, con il repository intorno a 40,8k stelle e 4,8k fork. I numeri esatti continueranno a muoversi; quello che conta è il pattern: Pi rilascia in fretta, e il changelog recente racconta un core che si irrobustisce invece di gonfiarsi.

Cosa è cambiato nelle ultime release

Vale la pena leggere il flusso delle release recenti, perché dice esattamente dove sta andando Pi:

• I workflow basati su package sono diventati di prima classe. Installi da npm, shorthand GitHub, HTTPS, SSH o path locali con pi install, fissi le versioni con i ref, aggiorni Pi e package separatamente e salvi i package di progetto sotto .pi/ con -l.
• Le skill seguono lo standard Agent Skills. Pi scansiona le cartelle globali e di progetto, espone le skill come /skill:name, carica le istruzioni complete solo quando servono e dalle impostazioni può puntare perfino alle directory skill di Claude Code o Codex.
• Le estensioni sono il vero layer plugin. Possono registrare tool, comandi, shortcut, flag, componenti TUI custom, event handler, compaction personalizzata, permission gate, protezione dei path, checkpoint Git, esecuzione SSH e integrazioni provider.
• La scelta dei provider si è fatta seria. Pi supporta provider via API key e flussi subscription/OAuth tramite /login, con liste di modelli tool-capable aggiornate a ogni release. Le note recenti includono routing OpenRouter, autenticazione Bedrock bearer-token, fix al conteggio dei service tier, migliorie alla prompt-cache affinity, mapping più accurati dei thinking level per modello e supporto DeepSeek provider per V4 Flash/Pro tramite DEEPSEEK_API_KEY.
• Login e scelta del modello sono più pratici. La linea v0.70 aggiunge la ricerca fuzzy nel selettore di /login, etichette sulla sorgente dell'autenticazione, default aggiornati e avvisi più chiari quando manca un modello o una credenziale.
• L'inferenza lunga si può domare. I controlli su timeout e retry dei provider ora vivono in — cosa concreta quando lavori con modelli locali, provider sotto carico o richieste di reasoning lunghe.

La lettura pratica è una sola: Pi non sta accumulando funzionalità nel core. Sta trasformando il core in un substrato stabile, e sposta il workflow vero dove deve stare — contesto di progetto, package, estensioni e skill.

Lo stack Pi, oggi

| Layer | Cosa configurare | Perché conta | | --- | --- | --- | | AGENTS.md | Regole di progetto, comandi, architettura, azioni vietate | Contesto sempre caricato, senza istruzioni nascoste | | .pi/settings.json | Default di progetto, modello, thinking level, package, skill, compaction, retry | Setup riproducibile per il team, non folklore personale da terminale | | .pi/extensions/ | Hook TypeScript, tool, comandi, safety gate, widget UI | Il posto giusto per costruire ciò che Pi si rifiuta — di proposito — di integrare | | .pi/skills/ o .agents/skills/ | Workflow profondi on-demand, script, riferimenti | Progressive disclosure senza bruciare contesto a ogni turno | | .pi/prompts/ | Template slash-command per i lavori ricorrenti | Prompt di qualità ripetibili, senza copia-incolla | | .pi/themes/ | Stile visuale | Pura ergonomia, ma utile se la TUI resta aperta tutto il giorno | | models.json | Provider custom, endpoint OpenAI-compatible, gateway Ollama/vLLM | Routing tra modelli hosted, locali e self-hosted |

È qui che Pi smette di somigliare a un prodotto. Un prodotto decide il workflow al posto tuo. Pi ti consegna un harness piccolo e ti chiede di scrivere il workflow, esplicitamente.

Cosa significano davvero le release v0.70

La linea v0.70 non è un bump cosmetico. Avvicina Pi a un vero sistema operativo per agenti:

• DeepSeek V4 diventa un percorso provider di prima classe. Se stai provando deepseek-v4-pro o deepseek-v4-flash, Pi tratta DeepSeek come provider configurato, senza passare da workaround OpenAI-compatible.
• I fallimenti dei provider diventano configurabili. Timeout e retry appartengono ai settings, non a wrapper shell sparsi per il sistema. Con modelli locali, cloud saturi e richieste long-context, fa la differenza.
• La scelta del modello è meno fragile. /login ricercabile, etichette sui provider e default aggiornati tolgono l'attrito operativo che di solito rende antipatici gli agenti multi-provider.
• Il comportamento nel terminale è più conservativo. I progress indicator sono opt-in: il default giusto per terminali, multiplexer, shell remote e sessioni registrate.

Il filo conduttore è coerente: Pi aggiunge superfici di controllo, non automazione nascosta. Che è esattamente quello che ci si aspetta da un runtime serio per coding agent.

L'origine: la frustrazione come principio di design

La frustrazione di Mario Zechner era precisa, tecnica. Claude Code — lo strumento che usava ogni giorno — era diventato, parole sue, "un'astronave con l'80% di funzionalità di cui non ho alcun bisogno." E i problemi erano concreti:

• System prompt instabile: prompt e definizioni dei tool cambiavano a ogni release, rompendo in silenzio workflow costruiti con cura.
• Context engineering alla cieca: il framework iniettava contenuto nella finestra di contesto senza mostrarlo nell'interfaccia — impossibile sapere cosa vedesse davvero il modello.
• Proliferazione dei tool: decine di strumenti sovrapposti si contendevano l'attenzione del modello, consumando budget di contesto già solo con le descrizioni.

La sua tesi: riduci un agente di coding al minimo assoluto — un system prompt minuscolo, quattro tool, piena trasparenza sul contesto — e i modelli di frontiera lavoreranno meglio, non peggio. Nel training c'è già tutto quello che serve al modello per fare l'agente di coding.

I risultati gli hanno dato ragione. Pi con Claude Opus ha retto il confronto con Codex, Cursor e Windsurf su Terminal-Bench 2.0 — con un system prompt sotto i 100 token e quattro tool in croce.

Pi contro tutti: il posizionamento

Il posizionamento è voluto. Pi occupa uno spazio che nessun altro rivendica: massima estensibilità, nucleo minimo. Non compete con Claude Code sulle funzionalità — sostiene che la maggior parte di quelle funzionalità non dovrebbe proprio stare nel framework.

Il grafico qui sopra racconta la storia da solo. Un system prompt che consuma 10.000 token sono 10.000 token che il modello non può spendere sul tuo codice. L'approccio di Pi: dai al modello gli strumenti, dagli il contesto del progetto (AGENTS.md), e lascialo lavorare.

Il monorepo: un'architettura a strati

Pi vive in badlogic/pi-mono — un monorepo TypeScript con npm workspaces e dipendenze a strati imposte con rigore. Il grafo delle dipendenze è un DAG: i pacchetti di base hanno zero dipendenze interne, e ogni strato può dipendere solo da quelli sotto di sé.

Non è un'architettura nata per caso. Ogni pacchetto si usa da solo: pi-ai per l'elaborazione batch di LLM senza alcuna infrastruttura agentica, pi-agent-core per incastonare un loop ReAct nella tua applicazione senza la TUI. Strati componibili, non un monolite.

pi-ai: un'unica API per tutti gli LLM

Il fondamento di tutto il resto. pi-ai mappa oltre 15 provider LLM su un'unica interfaccia — e ci riesce partendo da una constatazione tanto semplice quanto liberatoria:

La superficie dell'API

import { complete, completeStreaming } from "@mariozechner/pi-ai";
 
// Simple completion
const response = await complete({
  provider: "anthropic",
  model: "claude-sonnet-4-20250514",
  messages: [{ role: "user", content: "Explain Pi in one sentence." }],
});
 
// Streaming with abort support
const stream = completeStreaming({
  provider: "openai",

Context handoff: la funzionalità killer

La capacità più rara di Pi: una sessione può attraversare più provider LLM nella stessa conversazione. Passi da Claude a GPT a metà lavoro, e l'intero contesto — tracce di ragionamento comprese — viene serializzato e riformattato per il nuovo provider.

// Start with Claude for complex reasoning
const msg1 = await complete({
  provider: "anthropic",
  model: "claude-sonnet-4-20250514",
  messages: conversationHistory,
});
 
// Switch to a cheaper model for routine tasks
const 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: è preservazione completa dello stato attraverso formati API fondamentalmente diversi. Nessun'altra libreria LLM unificata lo fa.

Risultati dei tool sdoppiati

Altra idea di Pi: un tool può restituire contenuti separati per il modello e per l'interfaccia. All'LLM arriva un riassunto testuale asciutto; alla TUI arrivano dati strutturati per una resa ricca:

const tool = {
  name: "search_codebase",
  execute: async (args) => {
    const results = await searchFiles(args.query);
    return {
      llm: `Found ${results.length} matches in ${results.map(r => r.file).join(", ")}`,
      ui: { type:

pi-agent-core: il loop ReAct in ~200 righe

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: un LLM rende molto di più quando può ragionare, agire, osservare e ragionare di nuovo, invece di rispondere in un colpo solo.

L'implementazione di Pi è minimale e ispezionabile da cima a fondo.

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

La pipeline di validazione dei tool

Ogni chiamata a un tool passa da una pipeline di validazione rigorosa. Gli schemi TypeBox danno type safety a compile time E validazione a runtime, con messaggi d'errore dettagliati quando gli argomenti non tornano:

import { Type } from "@sinclair/typebox";
 
const ReadTool = {
  name: "read",
  description: "Read file contents",
  schema: Type.Object({
    path: Type.String({ description: "Absolute file path" }),
    offset: Type.Optional(Type.Number({ minimum: 0 })),
    limit: Type.Optional(Type

Messaggi in coda: steering contro follow-up

Mentre l'agente è in streaming puoi scrivergli senza aspettare. Pi distingue due modi di iniettare un messaggio, e sono due modi profondamente diversi:

Lo steering interrompe la generazione in corso e reindirizza l'agente. Il follow-up aspetta che il turno si chiuda e viene elaborato in quello dopo. Nella pratica questa distinzione vale oro: è la differenza tra "fermati, fai quest'altro" e "ah, quando hai finito, anche questo".

Quattro tool, non uno di più

Niente search_codebase. Niente get_git_history. Niente list_directory. Per tutto ciò che non è I/O su file, il modello usa bash. E funziona, per tre ragioni:

1. I modelli di frontiera conoscono già questi tool. Sono stati addestrati a fondo, con RL, proprio su scenari da agente di coding.
2. Ogni tool in più si mangia contesto. Le descrizioni dei tool sono care: viaggiano dentro ogni singola richiesta.
3. Bash è universale. grep -r, find ., git log — comandi che il modello conosce come le sue tasche.

I tool opzionali in sola lettura

Per le sessioni di pura esplorazione (per esempio l'onboarding su una codebase nuova), Pi ha la modalità read-only:

pi --tools read,grep,find,ls

Disabilita write, edit e bash: l'agente esplora ma non tocca nulla. Perfetto per code review e ricognizione dell'architettura.

Sessioni: l'albero JSONL

Le sessioni di Pi sono file JSONL append-only in cui ogni riga è un nodo con un id e un parentId. Ne esce una struttura ad albero che abilita il branching: torni a un punto qualsiasi della conversazione e riparti da lì, creando un ramo nuovo senza perdere i precedenti — tutto 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

Il nodo b1 si dirama da a2 e apre una linea temporale alternativa. I due percorsi convivono nello stesso file. L'API SessionManager offre le operazioni per elencare, creare, riprendere e ramificare le sessioni.

Compaction: sessioni senza fine

Quando una sessione si avvicina all'80% della finestra di contesto (soglia configurabile), Pi fa scattare la compaction: i messaggi più vecchi vengono sostituiti da un riassunto generato da un modello economico (Claude Haiku, per dire). Risultato: sessioni di lunghezza illimitata senza degradare la qualità.

La soglia si configura — e il modello che riassume può essere diverso da quello principale. In pratica, Haiku per i riassunti e Opus per il ragionamento è un'accoppiata che rende benissimo e costa pochissimo.

Le quattro modalità operative

Tutte e quattro condividono una sola astrazione, AgentSession. A cambiare è soltanto il livello di I/O.

Modalità SDK: come OpenClaw usa Pi

OpenClaw — l'assistente AI personale da oltre 250K stelle — usa la modalità SDK di Pi. Non lancia Pi come sottoprocesso: lo importa e lo istanzia direttamente, con pieno controllo del ciclo di vita.

import { createAgentSession } from "@mariozechner/pi-agent-core";
 
const session = createAgentSession({
  provider: "anthropic",
  model: "claude-sonnet-4-20250514",
  tools: [...defaultTools, ...customTools],
  extensions: [securityAudit, messageFormatter],
  onMessage: (msg) => gateway.send(channel, msg),
});
 
// Handle incoming message from WhatsApp/Telegram/Slack

È il pattern che ha reso possibile OpenClaw. L'"hack del weekend" di Peter Steinberger ha collegato il core agentico di Pi a un gateway di messaggistica multipiattaforma — ed è diventato virale perché il motore sotto (Pi) era abbastanza solido da reggere carichi reali, multi-canale.

Il sistema di estensioni

Le estensioni sono moduli TypeScript caricati da jiti — un transpiler TypeScript/ESM a runtime che non richiede alcuna fase di build. Il che abilita l'hot-reload: modifichi il file .ts, digiti /reload, e le modifiche sono già attive.

Anatomia di un'estensione

// my-extension.ts
import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
import { Type } from "typebox";
 
export default function (pi: ExtensionAPI) {
  // Add a custom slash command
  pi.registerCommand("review", {
    description: "Review staged changes",
    handler: async (_args, ctx) => {
      ctx.ui.notify("Run git diff --staged, then ask Pi to review the diff.

Il paradigma dell'auto-estensione

Ed eccola, la capacità più radicale di Pi. Siccome le estensioni sono TypeScript caricato senza build, l'agente può scrivere e ricaricare a caldo le proprie estensioni. Il flusso:

1. Descrivi cosa vuoi: "Mi serve un comando /deploy che lanci la nostra pipeline di staging"
2. Pi scrive l'estensione come file .ts
3. Digiti /reload
4. Pi prova il nuovo comando
5. Se fallisce, Pi legge l'errore, corregge il codice, ricarica e riprova

Armin Ronacher (il creatore di Flask e Jinja2) l'ha descritto come "software malleabile come l'argilla." Tutte le sue estensioni Pi — /answer, /todos, /review, /files — le ha scritte Pi stesso, non Armin. Lui ha descritto i requisiti, ha indicato all'agente qualche esempio, e Pi le ha implementate da solo.

Il system prompt: ~100 token

Questo è il system prompt di Pi, per intero, riprodotto dal codice sorgente. Mettilo accanto ai ~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 va a:

La gerarchia si carica in quest'ordine:

1. System prompt (~100 token)
2. Definizioni dei tool (~900 token)
3. File AGENTS.md (contesto di progetto, controllato da te)
4. Skill (progressive disclosure — caricate su richiesta)
5. Cronologia della conversazione (il grosso del contesto)

La maggior parte del budget la governi tu, attraverso AGENTS.md. È l'esatto contrario di Claude Code, dove il framework si prende quasi tutto il contesto e a te resta quel che avanza.

Skill: lo standard agentskills.io

Pi implementa agentskills.io, uno standard aperto per pacchetti di skill portabili. Una skill scritta per Pi funziona identica in Claude Code, Codex CLI, Amp e Droid.

Il formato SKILL.md

---
name: code-review
version: 1.0.0
description: Automated code review with style checks
triggers:
  - /review
  - "review this"
---
 
# Code Review Skill
 
You are a code review assistant. When activated:
 
1. Read the staged git diff
2. Check for:
   - Security vulnerabilities
   - Performance issues
   - Style violations
   - Missing error handling
3. Provide actionable feedback with line references

Le skill vivono di progressive disclosure: il contenuto completo entra nel contesto solo quando vengono attivate, non all'avvio della sessione. Il contesto base resta snello, la profondità arriva su richiesta.

La superficie attuale di package e skill

| Package o posizione | Cos'è | Quando usarlo | | --- | --- | --- | | pi-skills | Il package ufficiale di skill Pi riutilizzabili | Code review, test, documentazione e workflow agentici ripetibili | | @ollama/pi-web-search | Tool web search/fetch per Pi mantenuti da Ollama | Ricerca, audit SEO, verifica della documentazione | | pi-autoresearch | Package per cicli autonomi di esperimenti, citato dalla documentazione Ollama | Ottimizzare target misurabili: velocità dei test, bundle size, build time, Lighthouse score | | .pi/skills/ | Skill locali del progetto | Procedure specifiche del repo, che viaggiano col codice | | ~/.pi/agent/skills/ | Skill personali globali | I workflow tuoi, da avere in ogni progetto | | Directory skill di Claude Code / Codex | Cartelle skill esterne configurate dalle impostazioni Pi | Riusare una libreria skill esistente senza duplicare file |

Pattern agentici: cinque modi di usare Pi

Pattern 1: ReAct (il default)

Il comportamento predefinito. Zero configurazione — il modello decide da solo quando chiamare i tool:

pi "Fix the failing tests in src/auth/"

Pattern 2: Plan-and-Execute

pi "Write a TODO.md plan for refactoring the payment module to Stripe v3. Wait for approval before editing."

Pi non include un plan mode built-in, e lo fa apposta. Il pattern nativo è un piano scritto su file (TODO.md, PLAN.md, il testo di una issue), oppure un'estensione o un package di progetto che implementa il workflow di pianificazione che preferisci.

Pattern 3: Multi-agent (orchestratore + specialisti)

Nemmeno i sub-agent sono built-in, sempre di proposito. Usa sottoprocessi pi --print, pannelli tmux, oppure un'estensione o un package che implementa il routing verso gli specialisti:

# agents/security-reviewer.md
---
name: security-reviewer
model: claude-sonnet-4-20250514
tools: [read, grep, find]
---
You are a security specialist. Review code for OWASP Top 10 vulnerabilities.

Pattern 4: Reflection

Fai passare l'output dell'agente primario da un revisore specializzato prima di consegnarlo:

pi "Implement the feature, then run a second read-only review pass before summarizing."

Pattern 5: Caricamento dinamico dei tool

Oltre i 50 tool l'accuratezza degrada. Caricali progressivamente:

pi.on("resources_discover", async () => {
  // Only load tools relevant to current context
  const packageJson = await readFile("package.json");
  if (packageJson.includes("prisma")) {
    pi.registerTool(prismaQueryTool);
  }
});

La storia di OpenClaw: da hack del weekend a 250K stelle

OpenClaw nasce come "hack del weekend" dello sviluppatore austriaco Peter Steinberger. L'idea: un assistente AI personale che gira sui tuoi dispositivi e ti risponde sui canali che usi già — WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, IRC, Microsoft Teams, Matrix, LINE e altri ancora.

L'architettura è lineare: OpenClaw è un gateway di messaggistica che usa l'SDK createAgentSession() di Pi per incorporare un agente di coding completo. Ogni canale ha la sua sessione isolata. Il sandboxing Docker fa girare il codice dell'agente in sicurezza. Gli eventi schedulati abilitano trigger in stile cron.

Perché è stato Pi a rendere possibile OpenClaw

1. Modalità SDK: Pi si incorpora come libreria, non come sottoprocesso — pieno controllo del ciclo di vita
2. Agnosticismo sul provider: ognuno sceglie il suo LLM (Claude, GPT, Gemini, modelli locali via Ollama)
3. Sistema di estensioni: OpenClaw aggiunge estensioni custom per le funzionalità di piattaforma
4. Persistenza delle sessioni: con l'albero JSONL le conversazioni sopravvivono ai riavvii
5. Footprint minimo: il core minuscolo di Pi significa avvio rapido e poca memoria

L'integrazione con Ollama

ollama launch pi
ollama launch pi --config
ollama launch pi --model qwen3.5:cloud
pi install npm:@ollama/pi-web-search

L'integrazione Pi di Ollama è oggi il punto d'ingresso più pulito per i modelli locali: installa Pi, configura Ollama come provider, include i tool web e apre una sessione interattiva. La documentazione Ollama segnala anche @ollama/pi-web-search per web search e fetch, e pi-autoresearch per cicli autonomi di esperimenti che ottimizzano target misurabili — velocità dei test, bundle size, build time, training loss, Lighthouse score.

La TUI: retained mode contro immediate mode

La terminal UI di Pi (pi-tui) fa una scelta architetturale che nessun altro coding agent fa:

Con il retained mode, la TUI di Pi non sfarfalla mai. I componenti persistono tra i frame, tengono in cache il proprio output renderizzato e ridisegnano solo ciò che è cambiato. È lo stesso rendering differenziale di React — applicato al terminale.

Le estensioni hanno pieno accesso al sistema di componenti: barre di progresso, tabelle, menu di selezione, blocchi di codice con syntax highlighting — interfacce interattive che si fondono con l'output dell'agente.

I sette modi in cui un agente fallisce (e come Pi li disinnesca)

Economia del contesto: perché ogni token conta

Il grafico spiega perché il minimalismo di Pi vince anche sul piano economico. Se il framework consuma 15.000 token prima ancora del tuo primo messaggio, quel sovrapprezzo lo paghi su ogni singola chiamata API. Su una sessione lunga, centinaia di turni, il costo cumulato di un system prompt gonfio diventa una cifra seria.

L'approccio di Pi: ~1.000 token per system prompt e tool. Il resto del budget è tuo.

La configurazione Pi per lavorare sul serio

Se Pi è il tuo agente di coding quotidiano, non usarlo come una CLI globale vuota. Trattalo come parte del repository. L'obiettivo non è appesantire Pi: è rendere il contratto dell'agente esplicito, versionato e revisionabile.

Step 1: installa e scegli il percorso provider

npm install -g @mariozechner/pi-coding-agent
pi /login

Usa /login per i provider in abbonamento/OAuth come Claude, ChatGPT/Codex, Copilot, Gemini CLI o Antigravity. Usa le API key quando vuoi billing diretto e credenziali riproducibili:

export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export DEEPSEEK_API_KEY=sk-...

Per i modelli Ollama, locali o cloud, la via pulita ora è questa:

ollama launch pi
ollama launch pi --model qwen3.5:cloud

L'integrazione Ollama installa Pi, configura il provider, aggiunge i tool web e apre una sessione interattiva. Se ti serve il controllo manuale, definisci il provider in ~/.pi/agent/models.json e imposta defaultProvider / defaultModel nei settings.

Step 2: metti le regole in AGENTS.md

# Agent Contract
 
## Project
- Next.js, TypeScript, Tailwind CSS, PostgreSQL.
- Production deploys through Vercel.
- Never modify secrets, billing, DNS, auth providers, or database migrations without explicit approval.
 
## Commands
- Typecheck: npm run typecheck
- Lint: npm run lint
- Tests: npm test
- Build: npm run build
 
## Working Rules
- Read existing patterns before editing.
- Prefer small patches.
- Do not revert unrelated user changes.
- Before finalizing, report changed files and verification results.

Questo file vale più di qualsiasi prompt furbo. Pi carica AGENTS.md da posizioni globali, parent e di progetto: le regole personali le tieni a livello globale, quelle del repository nel repository.

Step 3: aggiungi .pi/settings.json

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "enabledModels": [
    "claude-*",
    "openai/gpt-*",
    "deepseek/*",
    "ollama/*"
  ],
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,

Non copiare i nomi dei modelli a occhi chiusi: usa pi --list-models e adattali ai provider che usi davvero. La parte che conta è la struttura — modello di default, cycling dei modelli, riserva per la compaction, retry policy, package di progetto e una scelta esplicita sulla telemetry.

Step 4: installa i package giusti

pi install npm:pi-skills -l
pi install npm:@ollama/pi-web-search -l
pi list
pi config

Installazioni project-local (-l) quando il package fa parte del workflow del repository; globali per le preferenze personali. E fissa le versioni quando il workflow deve restare stabile:

pi install git:github.com/user/repo@v1.2.0 -l

La regola di sicurezza è una: i package Pi eseguono codice con i tuoi permessi. Revisiona i package di terze parti prima di installarli — le estensioni soprattutto.

Step 5: aggiungi skill per il lavoro profondo

.pi/skills/
  code-review/SKILL.md
  release-check/SKILL.md
  incident-response/SKILL.md

Le skill sono il posto giusto per i workflow troppo grandi per AGENTS.md: checklist di review, procedure di deploy, playbook di migrazione dati, audit SEO, procedure di browser testing, estrazione da PDF, protocolli di benchmark. Il modello vede solo nome e descrizione finché non gli servono le istruzioni complete — e la finestra di contesto resta pulita.

Step 6: aggiungi una safety extension

// .pi/extensions/safety.ts
import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
export default function (pi: ExtensionAPI) {
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName !== "bash") return;
 
    const command = String(event.input.command ?? "");
    const dangerous

Questa è la filosofia di Pi tradotta in codice. Invece di aspettare che il tool ufficiale implementi il permission system dei tuoi sogni, scrivi la policy che serve al tuo repo. Venti righe, fatto.

Step 7: usa la modalità giusta per il lavoro giusto

# Daily development
pi
 
# Continue latest session
pi -c
 
# Read-only audit
pi --tools read,grep,find,ls -p "Find deployment risks in this repository."
 
# Scriptable one-shot task
cat diff.txt | pi -p "Write a focused PR review."
 
# Integration mode for editors, dashboards, or bots
pi --mode rpc

La mia raccomandazione, a oggi:

| Workload | Setup Pi | | --- | --- | | Architettura e debugging difficile | Modello reasoning forte, --thinking high, tool completi | | Edit ripetitivi ed economici | Modello più rapido, thinking normale, istruzioni circoscritte ai file | | Security review | Prima allowlist read-only, poi permesso esplicito di edit | | Documentazione e SEO | Workflow con skill più estensione browser/search | | Lavoro locale e privato | Provider Ollama, package web-search solo quando serve | | Automazione CI | pi -p o modalità JSON/RPC con tool stretti |

Il setup che fa la differenza non è un plugin magico. È un sistema a strati: istruzioni di progetto stabili, settings riproducibili, routing esplicito dei modelli, package revisionati, skill on-demand e piccole estensioni per le cose a cui il tuo team tiene davvero.

Perché l'open source ridotto all'osso vince

La lezione di Pi non è che il minimalismo vince sempre. È che il minimalismo nei posti giusti — system prompt, set di tool, loop principale — libera spazio per il massimalismo dove conta: nel controllo che hai su contesto, estensioni e workflow.

Claude Code è un prodotto eccellente. Cursor è un prodotto eccellente. Ma sono prodotti: pensati per l'utente medio, ottimizzati per il caso comune. Pi è un toolkit, pensato per chi vuole capire e governare ogni singolo token che entra nella finestra di contesto del proprio agente.

I fatti, aggiornati allo stato pubblico del progetto al 27 aprile 2026:

• Oltre 40.800 stelle GitHub sul repository core
• Oltre 4.800 fork sullo stesso repository
• Oltre 250.000 stelle su OpenClaw (costruito sull'SDK di Pi)
• v0.70.2 come ultima release GitHub visibile durante questo aggiornamento
• Supporto provider DeepSeek per V4 Flash/Pro tramite DEEPSEEK_API_KEY
• Integrazione Ollama che lo installa con un comando solo
• Pi package per estensioni, skill, prompt template e temi
• Compatibilità Agent Skills, che fissa uno standard di skill cross-agente
• Modalità RPC e SDK per costruire editor, dashboard, bot e prodotti agentici sopra lo stesso runtime

La prossima volta che litighi con un coding agent che fa qualcosa di inatteso — inietta contenuto che non puoi vedere, chiama tool che non hai chiesto, brucia contesto su funzionalità che non usi — ricordati che un'alternativa c'è. Una che si fida del modello, si fida di te, e si toglie di mezzo.

Quell'alternativa è Pi. E sta dimostrando che nell'era degli agenti AI il framework migliore è quello che quasi non c'è.

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

OpenClaw: openclaw/openclaw. L'analisi di Armin Ronacher: Pi: The Minimal Agent Within OpenClaw.

Fonti primarie dell'aggiornamento: sito ufficiale Pi, README Pi, documentazione extensions, documentazione skills, documentazione packages, documentazione settings, release GitHub v0.70.2, release GitHub v0.70.1, release GitHub v0.70.0 e integrazione Pi di Ollama.