Repo del giorno: pilotfish, l'orchestrazione multi-modello per Claude Code

🔍 Cos'è pilotfish

pilotfish è un layer di orchestrazione multi-modello per Claude Code: non un tool esterno né un router che intercetta le chiamate, ma una configurazione globale che vive sotto ~/.claude/ e ridisegna chi fa cosa. Il nome viene dal pesce pilota, che nuota accanto ai grandi predatori facendo il lavoro di routine: qui la sessione principale gira sulla famiglia opus e delega il volume a Sonnet e Haiku attraverso subagent con ruoli espliciti.

La genesi del progetto è quasi comica, e la racconta l'autore stesso nel README: una mattina il quota settimanale si era azzerato, e la prima cosa che ha fatto con l'allowance fresca di Fable 5 è stato chiedergli di indagare dove fosse finito quello della settimana prima. La risposta — la maggior parte dei token se ne va in ricerca, edit meccanici e test, non in giudizio — è diventata questa configurazione: tre file, zero codice runtime, installazione idempotente su ogni progetto.

repo       Nanako0129/pilotfish
cosa       orchestrazione multi-modello per Claude Code: frontiera pianifica,
           Sonnet/Haiku eseguono, verifier Opus a contesto fresco controllano
come       3 file di config sotto ~/.claude/ · 8 ruoli subagent · zero runtime
chicca     il benchmark Anthropic che lo giustifica: 96% delle prestazioni
           al 46% del costo con orchestratore + worker Sonnet
licenza    MIT · ~580 stelle · nato l'8 luglio 2026, release fitte

⚙️ Otto ruoli, tre livelli di configurazione

L'architettura sta in tre livelli. Il livello macchina è ~/.claude/settings.json: definisce chi orchestra (l'alias opus) e la catena di fallbackModel per degradare con grazia quando il modello primario non è disponibile. Il livello ruoli è la cartella ~/.claude/agents/: otto agent in Markdown, ognuno pinnato via frontmatter sul tier giusto e sulla superficie di tool minima. Il livello policy è il CLAUDE.md utente: le regole di delega, scritte in termini di ruoli e mai di nomi di modello.

Gli otto ruoli coprono il ciclo di vita completo: scout ed Explore (Haiku) per le ricognizioni read-only, plan-verifier (Opus, read-only) che sfida il piano e risponde READY o REVISE strutturato, mech-executor (Sonnet, effort basso) per il lavoro meccanico completamente specificato, executor (Sonnet, effort medio) per l'implementazione che richiede giudizio, verifier (Opus a contesto fresco) che verifica l'esito e non corregge mai, più i due ruoli di sicurezza (security-reviewer e security-executor, entrambi Opus) con mandato correttezza-prima-del-costo.

💸 I numeri che giustificano il pattern

Quello che rende pilotfish più di un'opinione è che il pattern è benchmarkato da Anthropic stessa. Nei test pubblicati nella documentazione multi-agent, un orchestratore Fable 5 con worker Sonnet 5 raggiunge il 96% delle prestazioni della configurazione tutta-Fable per il 46% del costo (su BrowseComp: 86,8% contro 90,8% di accuratezza, 18,53 contro 40,56 dollari a problema). Il pattern inverso — Sonnet esecutore che consulta Fable come advisor — si ferma a circa il 92% per il 63% del costo: la divisione orchestratore/worker che pilotfish adotta vince su entrambi gli assi.

A scala hobbistica la direzione è la stessa: un esperimento di audit con dodici worker documentato da Developers Digest passa da 14,50 dollari (tutto Fable 5) a 6,10 con worker Sonnet e 3,70 con worker Haiku. E per chi è in abbonamento c'è un bonus specifico: i limiti settimanali di Claude usano due bucket, uno condiviso per tutti i modelli più uno aggiuntivo solo-Sonnet — instradare l'esecuzione su subagent Sonnet costa meno per token e attinge a quell'headroom dedicato in più.

🧪 Installazione: un runbook che l'agente legge

L'installazione è essa stessa un esercizio di vibe coding ben fatto: si clona la release pinnata, si avvia Claude Code dal checkout e si incolla un prompt che gli fa leggere il runbook locale install/AGENT-INSTALL.md. L'agente ispeziona la configurazione esistente, mostra un piano di merge — niente viene sovrascritto alla cieca — e applica solo dopo approvazione. Rilanciarla aggiorna in place.

Una scelta che apprezzo: il README sconsiglia esplicitamente la via comoda del prompt che punta al raw di GitHub, perché segue main senza pinning e perché la protezione anti prompt-injection di WebFetch può legittimamente intercettare un documento remoto che istruisce un'AI a installare software. La risposta suggerita non è disattivare la protezione, ma usare il checkout locale: postura di sicurezza rara nei tool di questa categoria.

git clone --branch v1.3.8 --depth 1 https://github.com/Nanako0129/pilotfish.git
cd pilotfish
claude

# poi, nella sessione Claude Code:
# "Read the local file install/AGENT-INSTALL.md in the current checkout
#  and follow it to install pilotfish into my global Claude Code configuration.
#  Show me the full plan of changes and get my approval before writing anything."

⚠️ Il caveat onesto: la delega automatica non è garantita

Qui il progetto dà il meglio in trasparenza. Un'installazione riuscita non garantisce che Claude Code deleghi spontaneamente: istruzioni a priorità più alta iniettate dal client possono frenare il dispatch degli agent, e un CLAUDE.md utente non può scavalcarle. Il README documenta gli esperimenti — su Pro due tentativi senza cue non hanno dispatchato nulla; su Max la topologia attesa è emersa in un tentativo positivo su quattro — e traccia tutto in issue pubbliche, con i dati per cella in benchmarks/spontaneous-dispatch.

La soluzione pragmatica è un opt-in esplicito: quando si vuole il ciclo di orchestrazione si aggiunge alla richiesta una riga che invoca pilotfish e il suo freno di dispatch. C'è anche un avviso prezioso che vale da solo la lettura: dalla versione 2.1.198 di Claude Code il subagent Explore integrato eredita il modello della sessione principale — se la sessione gira su Fable o Opus, ogni ricerca in background brucia token di fascia alta. pilotfish lo reindirizza su Haiku.

• La delega spontanea dipende dal client: iniezioni a priorità più alta possono sopprimerla; serve l'opt-in esplicito nella richiesta quando si vuole il lifecycle completo.
• Explore integrato eredita il modello della main session (da Claude Code 2.1.198): senza override, le ricerche di background girano sul tier più caro.
• Gli alias modello dipendono da provider e settings: opus può risolvere a deployment diversi; per pinning esatto usare l'ID completo del modello.
• Progetto giovane e in evoluzione rapida: nato l'8 luglio 2026, release frequenti; in ambienti condivisi conviene la release pinnata, non main.
• Config globale, non per-progetto: scrive sotto ~/.claude/ e convive con la configurazione esistente via merge, ma va revisionato il piano di modifiche prima di approvare.

🏢 Perché è interessante, per sviluppatori e PMI

Per chi sviluppa con Claude Code tutti i giorni, pilotfish è la risposta strutturata a un problema che prima si gestiva a mano con il comando /model e la disciplina personale. La separazione fra ruoli read-only e ruoli con scrittura, i verifier che non correggono mai, il freno che tiene il lavoro piccolo nella sessione principale: sono pattern che migliorano il flusso anche a prescindere dal risparmio, perché la verifica a contesto fresco batte l'auto-critica — lo dice la guida ufficiale di prompting di Anthropic, non solo l'autore del repo.

Per una PMI che sta adottando agenti di coding la questione è di budget e prevedibilità: i piani hanno limiti settimanali, i token di fascia alta sono la risorsa scarsa, e un team che li brucia in ricerche e edit meccanici se li ritrova esauriti per le decisioni architetturali dove servono davvero. Una policy di delega codificata in configurazione — uguale per tutti, versionabile, revisionabile — è un pezzo di governance concreta: trasforma «usate i modelli con buon senso» da raccomandazione a default operativo.

✅ Da dove partire

Il percorso che suggerisco è in tre passi. Primo: leggere il README e i documenti in docs/ — anche senza installare nulla, sono fra le analisi più oneste in circolazione su costi, quota e comportamento reale del dispatch dei subagent. Secondo: installare dalla release pinnata con il runbook, revisionare il piano di merge proposto e riavviare la sessione. Terzo: provare il ciclo completo su un task reale con l'opt-in esplicito, e osservare nei log chi fa cosa — quali ruoli vengono dispatchati, cosa torna dal verifier.

Il segnale più ampio è che l'orchestrazione multi-modello sta diventando una pratica documentata e benchmarkata, non un trucco da power user: Anthropic pubblica i numeri, i tool la impacchettano, e la differenza fra chi la adotta e chi no si misura direttamente in bolletta e in quota residuo il venerdì pomeriggio. pilotfish è un ottimo posto dove studiarla, perché tutta la policy è leggibile in tre file di testo.