Pi: il coding agent minimale che si piega al tuo workflow

Negli ultimi mesi ho provato praticamente ogni coding agent da terminale. Quasi tutti seguono la stessa ricetta: più feature, più popup, più magia opaca. Poi è arrivato pi, che fa la scommessa opposta — un harness minimale che si adatta al tuo workflow invece di imporne uno. Dopo qualche settimana di uso quotidiano, è diventato il mio default.

La filosofia: quattro tool e basta

Di default pi dà al modello quattro tool: read, write, edit e bash. Fine. Tutto il resto — sub-agent, plan mode, permission gate, integrazione MCP — non c’è, di proposito:

• Niente MCP. Costruisci CLI tool con un README, o aggiungi MCP con un’estensione.
• Niente sub-agent. Spawna istanze di pi in tmux, o costruiscili come li vuoi tu.
• Niente popup di permessi. Gira in un container, o scriviti il flow di conferma che si adatta al tuo threat model.
• Niente to-do integrati. Confondono i modelli. Usa un file TODO.md.

La prima reazione è “mancano cose”. La seconda, dopo un po’ d’uso, è che ogni feature “mancante” era in realtà un’opinione di qualcun altro sul mio modo di lavorare.

Partire ci mette trenta secondi

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

export ANTHROPIC_API_KEY=sk-ant-...
pi "Elenca tutti i file .ts in src/"

# oppure con la subscription esistente (Claude Pro/Max, ChatGPT, Copilot)
pi
/login

Supporta decine di provider — Anthropic, OpenAI, Gemini, Groq, OpenRouter, perfino llama.cpp in locale — e cambi modello al volo con /model o cicli tra i preferiti con Ctrl+P.

L’estensibilità è il prodotto

Il cuore di pi non sono le feature: è il fatto che tutto si estende in TypeScript, senza forkare nulla. Un’estensione è un modulo che registra tool, comandi, shortcut e componenti UI:

export default function (pi: ExtensionAPI) {
  pi.registerTool({ name: "deploy", ... });
  pi.registerCommand("stats", { ... });
  pi.on("tool_call", async (event, ctx) => {
    // permission gate, checkpoint git, quello che vuoi
  });
}

Accanto alle estensioni ci sono le skill (pacchetti di istruzioni on-demand secondo lo standard Agent Skills), i prompt template e i temi. Tutto condivisibile come pi package via npm o git:

pi install npm:@foo/pi-tools
pi install git:github.com/user/repo@v1
pi list

Vuoi il plan mode? C’è un package. Vuoi che sembri Claude Code? C’è un’estensione. Qualcuno ci ha fatto girare Doom dentro, mentre aspetta che l’agente finisca.

Le sessioni sono un albero, non un log

La feature che mi ha conquistato è la gestione delle sessioni. Ogni sessione è un file JSONL con struttura ad albero: ogni messaggio ha id e parentId, quindi puoi ramificare senza perdere nulla.

• /tree — salti a qualunque punto della conversazione e continui da lì
• /fork — nuova sessione da un messaggio precedente, con il prompt già in editor
• /compact — comprimi il contesto quando la sessione si allunga (anche automatico)

In pratica: sbagli approccio a metà task? Torni indietro di tre messaggi e riparti su un branch nuovo, con tutta la storia preservata nello stesso file. È il “git” delle conversazioni con l’agente che non sapevo di volere.

Non solo interattivo

Pi gira in quattro modalità: interattiva, print/JSON per gli script, RPC su stdin/stdout per integrarlo in altri processi, e SDK per embeddarlo nelle tue app:

import { createAgentSession, ModelRuntime, SessionManager } from "@earendil-works/pi-coding-agent";

const modelRuntime = await ModelRuntime.create();
const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  modelRuntime,
});

await session.prompt("Quali file ci sono nella directory corrente?");

La modalità print è perfetta nelle pipeline: cat README.md | pi -p "Riassumi".

La lezione

Dopo tre mesi con un agente dentro un repo di produzione avevo capito che il collo di bottiglia è la review, non la generazione. Pi aggiunge il secondo pezzo del puzzle: il collo di bottiglia dell’esperienza d’uso è la rigidità dello strumento, non la mancanza di feature.

Un agente con cento feature che non puoi cambiare vale meno di un agente con quattro tool che puoi estendere all’infinito.

Se il vostro workflow è già identico a quello immaginato dal vendor del vostro agent, tenetevelo stretto. Per tutti gli altri c’è pi.