Chi ha provato a far scrivere codice a un agente AI conosce bene cosa succede a volte. Chiedi un semplice pulsante per attivare il tema scuro sul tuo sito e ti ritrovi con un pacchetto npm in più, tre componenti nuovi, un sistema per memorizzare le preferenze e un file di configurazione per colori che non cambierai mai, quando sarebbe bastata una decina di righe di CSS. Ponytail nasce per correggere proprio questa tendenza. Si tratta di un insieme di regole open source, con licenza MIT, che spinge l’agente a comportarsi come uno sviluppatore esperto e un po’ pigro, di quelli che prima di scrivere una riga si chiedono se serva, se esista già nel progetto o se basti una funzione inclusa nel linguaggio.
Pubblicato su GitHub da Dietrich Gebert, Ponytail ha superato le 170.000 stelle ed è arrivato alla quinta versione, con adattatori per una ventina di strumenti: OpenCode, Claude Code, Codex, Gemini CLI, Cursor, Copilot e altri ancora. Il dettaglio che lo distingue da un semplice scrivi meno è che non taglia alla cieca, perché validazione degli input, gestione degli errori, sicurezza e accessibilità restano fuori discussione.
Nei test pubblicati con il progetto, eseguiti con Opus 5.5, il codice prodotto si dimezza e la spesa per sessione scende di circa un quarto. In questa guida trovi come funziona, come installarlo passo per passo su OpenCode 2, sulle app di Claude e su Codex, e quali limiti conviene conoscere prima di affidargli un progetto a cui tieni.
Una scala in sette gradini prima di ogni riga di codice
Dal punto di vista tecnico, Ponytail è prima di tutto un file di testo, SKILL.md, cioè una skill. Con questo termine si indica un pacchetto di istruzioni che l’agente carica nel proprio contesto e consulta ogni volta che il compito lo richiede, un po’ come un regolamento interno appeso in ufficio. Non ci sono programmi da eseguire né servizi in background, almeno nella versione base. Le varianti per i singoli strumenti aggiungono comandi e piccoli script di supporto, ma il cuore resta quel testo.
Il regolamento obbliga l’agente a risalire una scala di sette domande, fermandosi al primo gradino che risolve il problema:
- Serve. Se il bisogno è solo ipotetico, la funzione non si scrive e lo si dichiara in una riga.
- Esiste già. Se nel progetto c’è un’utilità o un componente equivalente, si riusa quello.
- Libreria standard. Se il linguaggio offre già una soluzione, si sceglie quella.
- Piattaforma nativa. Un campo data HTML al posto di una libreria per calendari, un vincolo nel database invece di controlli scritti a mano.
- Dipendenze presenti. Si sfrutta ciò che è già installato e non si aggiunge un pacchetto per tre righe di codice.
- Una riga. Se basta una riga, si scrive una riga.
- Il minimo. Solo a questo punto l’agente scrive il codice più breve che funziona.
La scala entra in gioco dopo che l’agente ha letto il codice coinvolto, non al posto della comprensione. Quando corregge un bug, per esempio, deve prima cercare tutte le parti del programma che usano la funzione difettosa, perché una protezione nel punto condiviso è più piccola e più corretta di dieci toppe sparse.
Ogni risposta si chiude con una riga nel formato skipped: X, add when Y, cioè cosa è stato lasciato fuori e in quale situazione conviene aggiungerlo. Le scorciatoie volute, come una ricerca poco efficiente in liste lunghe, vengono segnate nel codice con un commento che inizia con ponytail: e indica il limite insieme alla strada per superarlo. L’intensità si regola su tre livelli, che il progetto spiega con l’esempio di una cache per le risposte di un servizio web:
| Livello | Comportamento | Esempio della cache |
|---|---|---|
| lite | Costruisce ciò che chiedi, ma segnala l’alternativa più snella | Scrive la cache e ricorda che functools.lru_cache fa lo stesso in una riga |
| full (predefinito) | Applica tutta la scala | Usa lru_cache e dichiara di aver saltato la classe dedicata |
| ultra | Prima cancella, poi aggiunge | Niente cache finché un profiler non dimostra che serve |
Per il lavoro di tutti i giorni il livello full è la scelta giusta. Lite è utile se stai imparando e vuoi vedere entrambe le strade, mentre ultra ha senso sui prototipi da sperimentare.
Installare Ponytail su OpenCode 2
OpenCode è l’agente di programmazione open source che funziona con quasi qualsiasi modello, da quelli in cloud a quelli eseguiti in locale. A ottobre 2026 OpenCode è utilizzato attivamente da circa 2.000.000 di utenti e la versione 2, stabile dall’11 settembre 2026, ha cambiato parecchie cose: un server in background a cui si collegano terminale, app desktop ed editor, un nuovo sistema di plugin incompatibile con quello precedente e la lettura del solo file AGENTS.md, mentre CLAUDE.md viene ignorato.
Su Windows, OpenCode si installa con winget, il gestore di pacchetti integrato nel sistema. Se preferisci l’interfaccia grafica, esiste anche l’app desktop:
# Versione a riga di comando
winget install --id Anomaly.OpenCode -e
# App desktop (facoltativa)
winget install --id Anomaly.OpenCode.Desktop -e
# Verifica della versione installata
opencode --version
Su macOS e Linux il metodo più rapido è lo script ufficiale:
curl -fsSL https://opencode.ai/v2/install | bash
A questo punto Ponytail si aggiunge con un solo comando, che lo rende disponibile in tutti i progetti:
opencode plugin add @dietrichgebert/ponytail
opencode plugin list
Il secondo comando serve a verificare che il plugin compaia nell’elenco. Se invece vuoi attivarlo solo in un progetto, crea o modifica il file opencode.jsonc nella sua cartella principale (oppure .opencode/opencode.jsonc) e aggiungi la voce plugins:
{
"plugins": ["@dietrichgebert/ponytail"]
}
La configurazione globale si trova invece in ~/.config/opencode/opencode.jsonc. I due elenchi si sommano, quindi non c’è rischio che uno cancelli l’altro. Se hai scaricato il repository e vuoi usare la copia locale, la voce deve puntare a una cartella e non al singolo file, altrimenti OpenCode 2 restituisce l’errore configured plugin path must be a directory:
{
"plugins": ["C:/Sviluppo/ponytail/.opencode/plugins"]
}
Chi è rimasto su OpenCode 1 non ha il comando plugin add e deve usare la chiave al singolare, "plugin": ["@dietrichgebert/ponytail"]. Gli aggiornamenti, nella versione 2, passano da opencode plugin check e opencode plugin update, mentre opencode plugin remove @dietrichgebert/ponytail lo disinstalla.
Una volta avviato OpenCode, il plugin inserisce il regolamento a ogni turno e aggiunge i comandi /ponytail. Puoi digitare /ponytail lite all’inizio di una sessione didattica e /ponytail full per tornare alla normalità. Secondo me OpenCode è anche l’ambiente dove Ponytail rende di più, perché molti lo usano con modelli economici o locali, che tendono più dei grandi modelli a riempire il progetto di codice superfluo.
Se preferisci attivarlo solo su richiesta, lascia il plugin installato e imposta il livello predefinito su off. Basta creare il file %APPDATA%\ponytail\config.json (su macOS e Linux ~/.config/ponytail/config.json) con il valore "defaultMode": "off", oppure impostare la variabile d’ambiente da PowerShell con setx PONYTAIL_DEFAULT_MODE off, ricordandoti di riaprire il terminale e l’eventuale app desktop. Da quel momento ogni sessione parte con le regole spente, e ti basta digitare /ponytail full per accenderle fino alla chiusura della sessione.
Chi ragiona per progetto ha altre due strade. Invece di installarlo con opencode plugin add, che lo rende globale, puoi inserirlo nell’opencode.jsonc dei soli progetti che ti interessano. Al contrario, se è già installato ovunque, un trattino davanti al nome ("-@dietrichgebert/ponytail") lo esclude da un singolo progetto senza disinstallarlo. Tieni presente un dettaglio: se hai copiato nel progetto l’AGENTS.md di Ponytail, OpenCode lo carica sempre e le regole restano attive anche con il plugin spento.
Se tutto questo ti sembra complicato, c’è un’altra strada molto più semplice. Apri OpenCode, scegli un modello capace come DeepSeek V4.1 Flash e invia questo prompt:
Installa su OpenCode il plugin Ponytail (https://github.com/DietrichGebert/ponytail). Ponytail deve restare disattivato di default in ogni nuova sessione e attivarsi solo quando lo chiedo io, valido solo per quella sessione. Se non indico un livello, usa full. Non copiare AGENTS.md nei progetti. Al termine verifica l'installazione con "opencode plugin list" e spiegami quali file hai modificato.Il modello dovrebbe occuparsi da solo dell’installazione e della configurazione. Dalla sessione successiva le regole restano spente finché non chiedi di attivarle, e valgono solo per quella sessione. Prima di affidarti a questa configurazione, ti conviene aprire una nuova sessione e chiedere all’agente se Ponytail è attivo, per controlLe scorciatoie volute, come una ricerca poco efficiente su liste lunghe, vengono segnate nel codicelare che il risultato sia quello che volevi.
Claude Code, l’app desktop e le skill di claude.ai
Con Claude Code a riga di comando l’installazione richiede due comandi, da inviare in due messaggi separati:
/plugin marketplace add DietrichGebert/ponytail
/plugin install ponytail@ponytail
Gli stessi comandi funzionano nella scheda Code dell’app desktop di Claude. In alternativa puoi premere il pulsante + accanto al campo di testo, scegliere Plugins e poi Add plugin, mentre i marketplace registrati si gestiscono dalla voce Customize nella barra laterale. Per rimuoverlo basta /plugin remove ponytail.
Solo su Claude Code c’è una funzione in più, la band. Si tratta di una barra sopra il campo di testo che mostra costo, token consumati, tempo di lavoro dell’agente, quanto codice esistente è stato riutilizzato e lo stato dei test. Richiede Claude Code 2.1.290 o una versione successiva e funziona nel terminale e nell’app desktop, non nella chat di VS Code, nelle sessioni cloud o con claude -p. Si attiva con /ponytail band on, e con /ponytail band import puoi caricare anche le sessioni passate. I dati restano sul computer, nella cartella ~/.config/ponytail/band/.
Diverso è il caso della chat di Claude, sul web o nell’app desktop. Qui non ci sono plugin, ma puoi caricare il file SKILL.md come skill personale. Per prima cosa attiva Code execution and file creation in Settings > Capabilities, perché senza questa opzione non si attivano. Poi scarica il repository da GitHub come ZIP, estrailo e crea un nuovo archivio con la sola cartella della skill. Su Windows bastano due righe di PowerShell:
Expand-Archive .\ponytail-main.zip -DestinationPath .\ponytail-src
Compress-Archive -Path .\ponytail-src\ponytail-main\skills\ponytail -DestinationPath .\ponytail.zip
Il nome della cartella dentro lo ZIP deve restare ponytail. A quel punto apri Customize > Skills, premi +, scegli Create skill e poi Upload a skill. La skill compare nell’elenco con un interruttore per accenderla e spegnerla. In questa modalità mancano i comandi con la barra, ma Claude applica il regolamento da solo ogni volta che gli chiedi del codice. Se vuoi cambiare livello, ti basta scriverlo nel messaggio (per esempio “usa ponytail ultra”), mentre con “stop ponytail” lo disattivi per il resto della conversazione.
Codex e gli altri agenti compatibili
Su Codex, l’agente di OpenAI, la procedura ricorda quella di Claude Code, ma con un passaggio di sicurezza in più:
codex plugin marketplace add DietrichGebert/ponytail
codex plugin add ponytail@ponytail
Dopo l’installazione avvia codex, digita /hooks e approva i due hook di Ponytail. Gli hook sono piccoli script che l’agente esegue automaticamente in momenti precisi, per esempio all’inizio di una sessione, e Codex chiede il tuo consenso prima di lasciarli girare.
La stessa installazione vale per l’app desktop di Codex, che va semplicemente riavviata. L’estensione di Codex per VS Code legge invece il file AGENTS.md del progetto, e copiandolo in ~/.codex/AGENTS.md le regole valgono ovunque. Su Codex i comandi cambiano forma: /ponytail-review diventa $ponytail:ponytail-review.
Per gli altri strumenti alcuni hanno un’installazione dedicata, altri leggono un file di regole da copiare nel progetto, altri ancora caricano AGENTS.md senza alcuna configurazione. Va detto che non tutti gli strumenti ricevono le stesse funzioni. Gli adattatori basati solo su file di regole caricano il regolamento ma non i comandi, e Cursor con gli hook permette soltanto di cambiare livello. Su Cursor, inoltre, la cartella clonata deve restare dov’è, perché gli hook eseguono Node.js proprio da lì.
Cosa dicono i numeri
I dati che accompagnano la quinta versione vengono da un benchmark piuttosto curato. Sono state eseguite 585 sessioni di Claude Code con Opus 5.5, cioè 39 compiti ripetuti cinque volte in tre configurazioni (senza skill, con la versione 4.13 e con Ponytail 5). I compiti comprendono dodici richieste di funzioni su un’applicazione FastAPI e React, diciotto interventi mirati con controlli nascosti su bug e sicurezza e nove piccole app o esempi. Rispetto all’agente senza regole, Ponytail 5 scrive il 53% di righe in meno, riduce i tempi del 41% e i costi del 26%, con una spesa media che scende da 0,20 a 0,14 dollari per sessione.
Il dato che trovo più interessante, però, riguarda i test. Quando un compito ne richiedeva uno, l’agente senza regole lo ha scritto nel 68% dei casi, quello con Ponytail nel 98%. La correttezza resta in pratica invariata, con 87 controlli nascosti superati su 90 contro 86, e tutti i compiti di sicurezza sono andati a buon fine in ogni configurazione. In altre parole, meno codice non significa codice più fragile.
Il valore nascosto su ciò che è stato saltato
Ponytail corregge un difetto degli agenti attuali, la tendenza a costruire troppo. Tuttavia, dopo averne esaminato regole, comandi e benchmark, la parte di Ponytail che considero più utile non è solo il taglio del codice, che pure si vede subito nelle sessioni e sulla bolletta dei token. È quella riga finale con skipped e add when, che a ogni risposta dichiara cosa l’agente ha deciso di non fare e in quale situazione converrebbe farlo.
Per chi non programma tutto il giorno, o usa gli agenti per costruire piccoli strumenti personali, quella riga funziona come una breve lezione. Abitua a ragionare su cosa serve oggi e su cosa può aspettare, e rende evidenti le scelte che altrimenti l’agente prenderebbe in silenzio.
