Ho Creato un Mod Non Documentato di Claude Code, Guard Cede

I Claude Code Mods sono moduli TypeScript che girano dentro il motore di Claude Code e agganciano i suoi eventi come funzioni. Boris Cherny, che guida Claude Code in Anthropic, li ha annunciati con cinque parole: "Claude mods are landing now". Il post ha raccolto 2.400 like, e qualcuno aveva già costruito Tetris dentro il terminale. Tetris, Doom, e un animaletto che cresce mentre Claude esegue i tuoi test, tutto renderizzato sopra il prompt, a zero token.

L'annuncio non rimanda a nessuna pagina di documentazione. Rimanda a un GitHub issue aperto 12 giorni prima da un ingegnere Anthropic, con una condizione scritta al suo interno. Alice Poteat ha scritto che la risposta della community avrebbe probabilmente deciso se la funzione sarebbe stata rilasciata o no. 177 commenti dopo, la gente aveva martellato il binario contrassegnato, misurato i suoi timeout, e costruito giochi sopra di esso.

Misura	Valore
Like sull'annuncio	2.400
Commenti sul GitHub issue	177
Superficie tipizzata nella build di questa settimana	10.700 righe
Eventi sui nomi (build del thread dell'issue)	84 su 19
Mods su GitHub entro 48 ore	31

La pagina di documentazione, al momento in cui scriviamo, restituisce un 404. Questo articolo copre i quattro modi per estendere Claude Code, un Mod utile costruito e rotto apposta, e cosa resta instabile prima di spedirne uno.

L'albero sorgente lo definisce in una frase: un Mod è un plugin di Claude Code il cui comportamento vive in un hooks module. Una voce di registro aggancia gli eventi del motore come funzioni. Su disco, questo si traduce in una cartella plugin, un hooks manifest che nomina esattamente un modulo, e il modulo stesso.

Ogni hook è una funzione di tre cose: $, la porta da cui passa ogni effetto collaterale; l'evento; e la continuazione, il resto della catena sotto di te. Gli hook si annidano come middleware. Quello registrato per primo possiede l'evento, e niente più in basso nella catena può inibirlo. Quell'ordine è configurato, non installato. Nelle parole di Alice Poteat, l'ordine è impostato dalla configurazione, non da quando li hai installati.

Non esiste accesso ambientale. Tutto ciò che un Mod fa passa attraverso $, così un amministratore può verificare, consentire, negare o loggare qualsiasi evento. Un commentatore lo ha riassunto così: ciò che un plugin ha fatto è esattamente l'insieme delle chiamate che ha effettuato. Un singolo hook su * vede ogni evento, quindi un log di audit è una sola funzione. Un Mod può disegnare, perché l'interfaccia è React. Gira in process su Bun, a 50 microsecondi al 99° percentile. Una variabile d'ambiente lo attiva. Cosa vive davvero su $ è ancora in fase di progettazione con i partner early-access.

Uno shell hook è uno script che il motore chiama in un momento fisso. Riceve JSON in standard input e risponde con un exit code. La risposta ha un tetto: 8.000 caratteri di contesto restituiti, e 2.000 per alcuni hook. Nelle parole di Pratham, su Windows si rompono spesso in modi strani.

Un plugin è una scatola. Un manifest riunisce skill, agent, hook e server MCP. Si installa da un marketplace o si carica direttamente da una cartella su disco, e un comando valida la scatola prima che qualsiasi cosa venga eseguita.

Una skill è prosa che il modello legge quando ne ha bisogno. Il corpo si carica solo quando arriva un prompt corrispondente. Resta il modo più economico per cambiare comportamento.

Un Mod è la stessa scatola con un file in più: un hooks manifest che nomina un modulo, e quel modulo è TypeScript, tipizzato, in process, su ogni evento del motore. Questa è tutta la differenza.

Meccanismo	Cos'è	Esecuzione	Tetto
Shell hook	Script chiamato in un momento fisso	Subprocess, exit code	8.000 caratteri restituiti (2.000 per alcuni hook)
Plugin	Bundle di skill, agent, hook, server MCP	Installato o caricato da disco	Validato prima dell'esecuzione
Skill	Prosa caricata su un prompt corrispondente	Nel contesto del modello	Cambio più economico
Mod	Plugin più un hooks module TypeScript	In process, su ogni evento	Tipizzato, early access

I tipi provengono da un solo slash command, che scrive l'elenco completo di ciò che $ offre direttamente nel tuo progetto. I vecchi shell hook sono incapsulati, non ritirati. Su una build iniziale, Spencer Morley ha visto il wrapper fallire nel caricamento e restare comunque dichiarato. La regola pratica: per cambiare ciò che Claude sa, scrivi una skill; per eseguire uno script in un momento, uno shell hook; per spedire un bundle, un plugin; per sedersi dentro il motore, un Mod. Lo shell hook funziona ancora ovunque il flag sia disattivato.

Tre Mod sono inclusi nel binario e il loro codice sorgente è su GitHub: un default di sicurezza, un pannello diff, e telemetria.

Il default di sicurezza si colloca più all'esterno di tutti. Su una macchina con impostazioni gestite, o in un'organizzazione Team o Enterprise, niente di ciò che una persona installa arriva sopra di esso. Aggancia 12 eventi, e ogni hook compie una di tre mosse: continua oltre il tier utente, rifiuta un chiamante del tier utente per nome, o passa oltre. Fallisce in modo chiuso, e il commento nel codice lo dice in due parole. Questa è la parte che ha interessato il thread: un amministratore rimuove una possibilità da $, e niente di registrato più in basso può invocarla. Nelle parole di un commentatore, questo è categoricamente diverso dal chiedere a un plugin di non fare qualcosa.

Diff è un pannello accanto al transcript, che mostra le modifiche non committate della sessione file per file, aggiornato man mano che Claude modifica. È registrato all'avvio della sessione e si estende su 27 file di supporto, non un giocattolo.

Telemetry aggiunge un noun a $ dall'interno della creazione del motore. Attende ciò che sta sotto e restituisce quello più se stesso. Gira solo nelle build interne.

Il README dice di eseguirne uno dal sorgente e testarne uno dal sorgente. L'help sulla build odierna elenca validate, eval e details. Non c'è test nell'elenco, anche se l'help di test risponde comunque. Il tier integrato rifiuta anche la tua copia: spedisci un plugin con uno di quei nomi, e il binario carica il proprio.

Lo slash command che scrive i tipi produce, su questa build, 11.700 righe: 84 eventi su 23 noun. L'hook sulla chiamata a un tool risponde con un risultato o un diniego, mai il testo. Questa parte è impostata dal core.

Il Mod è tre file: il plugin manifest, l'hooks manifest con la sua unica riga, e il modulo. Il modulo è di 42 righe. Attende ciò che sta sotto, ripulisce il risultato, e lo restituisce. Quattro pattern coprono due formati di chiave vendor, un token GitHub, e qualsiasi cosa assegnata a una variabile chiamata key, secret o token.

Validate legge il sorgente prima che venga eseguito. Nomina l'evento che il modulo aggancia e l'unica cosa che chiama su $. L'unico avviso è un autore mancante. Caricato da disco con il flag attivo, il file di test contiene due chiavi, entrambe false per costruzione, e il modello legge "redacted". Nelle sue stesse parole, i valori sono tornati come redacted, quindi non può vedere cosa contengono.

Misura	Valore
Lunghezza del modulo	42 righe
Latenza dell'hop, worker incluso	28 ms
Token aggiunti alla sessione	0

Il motore registra l'hop come risolto da un hooks module. L'inventario non mostra skill, né agent, niente sempre attivo. Resta un limite: nascosto al modello non significa nascosto allo schermo. Il transcript mostra ancora ciò che il tool ha stampato. Quello è un Mod diverso, come ha notato Max di Ship Notes in una riga.

Stesso Mod, una riga aggiunta: uno sleep di 15 secondi prima della chiamata a ciò che sta sotto. Dieci secondi dopo, il motore rinuncia, riporta che l'hook ha superato il suo budget ed è stato saltato, e ciò che sta sotto viene eseguito al suo posto. Il comando gira comunque e stampa "hi".

Sostituisci lo sleep con un throw: 574 millisecondi, stesso verdetto, saltato, e il comando gira.

Caso	Tempo	Verdetto
Hook sano	28 ms	Risolto
Throw	574 ms	Saltato, comando eseguito
Blocco	oltre 10 s	Saltato, comando eseguito

Entrambi i fallimenti finiscono con la stessa parola: saltato. Il thread aveva misurato questa asimmetria una settimana prima. Una capacità mancante al caricamento fallisce in modo chiuso. Un hook oltre il budget fallisce in modo aperto: rumoroso ma aggirato, nelle parole di Spencer Morley. Un blocco senza motivazione manda semplicemente il modello verso un altro tool. Pratham lo ha visto scegliere un tool diverso e scrivere il file comunque.

La risposta sul tavolo è un catch. Alice Poteat propone un catch sul return dell'hook, che scatta se impieghi troppo tempo o lanci un errore. Una scrittura riscritta ha comunque bisogno di una nota per il modello: vede ciò che aveva chiesto di scrivere, per ragioni di caching, quindi aggiungi una riga di contesto. Il budget è anche l'isolamento. Il worker degli hook gira separatamente, e quando crasha, il motore lo fa ripartire e disattiva gli hook per la sessione. La correzione non è un budget più lungo ma un catch dichiarato.

Due giorni dopo: Tetris sopra il prompt e altri sette giochi, giocabili mentre Claude lavora, a zero token. Doom, l'originale del 1993, gira nel proprio processo; il Mod lo raggiunge via HTTP locale e ridisegna 10 volte al secondo. C'è un breathing pacer nello spinner, e un modello narrativo con 260.000 parametri che gira dentro il worker degli hook, con zero token API.

Il registro ha scansionato 31 Mods con validate. 14 possono eseguire processi host. 13 vedono ogni chiamata di tool.

Demo 8 del thread della community prometteva che una sola frase scrive un plugin che nasconde i segreti prima che il modello li legga. Ne abbiamo chiesto uno.

Misura	Valore
Tempo	4 min
Turni	34
Costo	1,23 $
Righe (più un file di test)	190, contro le nostre 42
Test	4 superati in un terzo di secondo

Etichetta ciò che nasconde per tipo, valida pulito, e non richiede né chiave API né chiamata al modello. Una risposta lo ha messo così: le allowlist sono il prodotto, Tetris è la demo.

I numeri stessi del registro sono l'avvertimento. 14 dei 31 Mods possono eseguire processi host, e l'unica verifica è un'impronta statica. L'help di eval lo dice da solo: una suite che passa non è una verifica di sicurezza.

Segnale	Valore
Eventi l'8	20
Eventi il 15	84
Versioni CLI in due settimane	14
Punti su Hacker News	2
Risposte alla domanda sulla compatibilità	0

Il budget di 10 secondi vive nel runtime, non nei tipi, come ha notato Marat. Non c'è una riga di changelog, nessuna pagina di documentazione, nessun post di lancio. Un rivale dice che Anthropic l'ha copiato: Ahmad Awais punta ai mods di Command Code, e ne scrive lui stesso l'esempio, quindi valuta di conseguenza. Il post "early access, APIs may change" ha raccolto 357 like.

Costruiscine uno ora se scrivi già hook e vuoi audit, redazione o un pannello. Aspetta se stai per spedirlo a un team prima che il contratto sia scritto. La stessa apertura è la ragione per cui il budget che fallisce in modo aperto, il disallineamento di tipo nelle chiamate MCP e il fallimento del wrapper sono stati trovati dagli utenti in pochi giorni.