Anche gli hook esistenti di Claude Code vengono eseguiti in risposta a eventi, come comando della shell, richiesta HTTP o prompt che configuri in un file di impostazioni. I gestori di un mod, invece, sono funzioni che vengono eseguite all’interno di Claude Code. Claude Code chiama hook entrambi i tipi: in queste pagine, “hook” indica un gestore di un mod, mentre il tipo definito nel file di impostazioni è un “hook delle impostazioni”.
Cosa può fare un mod
Gli hook delle impostazioni, le skill, le righe di stato e i server MCP funzionano dall’esterno di Claude Code: ciascuno esegue uno script, oppure fornisce a Claude testo o strumenti. Un mod viene eseguito all’interno di Claude Code, quindi può fare cose che loro non possono fare:- Disegnare un’interfaccia che puoi usare: un pannello accanto alla trascrizione o una fascia sopra il prompt, con schede, pulsanti e campi di testo. Consulta Disegnare nell’interfaccia.
- Ridisegnare l’interfaccia di Claude Code stessa: sostituire o modificare lo stile di parti che Claude Code disegna da sé, come la riga di una chiamata a uno strumento, lo spinner o la finestra di dialogo in cui Claude pone domande. Consulta Modificare ciò che Claude Code disegna già.
- Intervenire in una chiamata a uno strumento o in una richiesta: ad esempio, sospendere una chiamata a uno strumento mentre fai una domanda all’utente, rispondere senza eseguire lo strumento, oppure inviare una richiesta a un modello diverso. Consulta Controllare o modificare una chiamata a uno strumento e Seguire un turno.
- Eseguire il tuo codice con un comando: un
/commandche esegue subito la tua funzione, senza alcun turno di Claude, anche mentre Claude sta lavorando. Consulta Aggiungere un comando o uno strumento. - Condividere dati tra gli hook: gli hook di un mod condividono le variabili del suo file, quindi ciò che un hook registra, un altro può mostrarlo. Ad esempio, un hook può contare le chiamate agli strumenti mentre un altro mostra il conteggio accanto allo spinner, oppure uno può leggere l’utilizzo dei token di ogni richiesta mentre un altro lo rappresenta in un grafico in un pannello. Consulta Reagire agli eventi.
claude -p e nelle sessioni cloud. Se un hook delle impostazioni, una skill o un server MCP fa già ciò di cui hai bisogno, confrontali prima di scrivere un mod. Per gestire i mod per un’organizzazione, consulta Gestire i mod per la tua organizzazione.
Ottieni un mod
Per iniziare con un mod:- Usane uno che hai già: alcune funzionalità di Claude Code sono esse stesse dei mod, come
/diff. Consulta Mod integrati in Claude Code. - Creane uno: descrivi ciò che vuoi in una sessione di Claude Code e Claude scriverà il mod. Consulta Chiedi a Claude un mod. Per capire come funziona il codice di un mod, scrivine uno tu stesso.
- Installane uno: consulta Installa o aggiorna un mod, oppure prova un mod di esempio
Installa o aggiorna un mod
Un mod si installa come plugin, da un marketplace. Indica il nome del plugin, una@ e il nome del marketplace. Questi esempi installano un plugin chiamato token-chart da un marketplace chiamato your-org:
- In una sessione di Claude Code, esegui
/plugin install token-chart@your-org. - Nella tua shell, esegui
claude plugin install token-chart@your-org.
/reload-plugins in quella sessione per caricarlo. Altrimenti verrà caricato al prossimo avvio di Claude Code.
Prova un mod di esempio
Anthropic condivide mod di esempio nella directoryclaude-code/mods del repository claude-code-playground. Ognuno è un plugin completo e il suo README spiega come è stato realizzato. Il repository li condivide così come sono, senza supporto.
token-weather: disegna una previsione della tua finestra di contesto sopra il promptblast-radius: trattiene un comando di shell rischioso, comerm -rfo un force push, e mostra cosa modificherebbe, con pulsanti per procedere o annullarereplay-theater: aggiunge un comando/replayche ripercorre passo per passo le modifiche ai file effettuate da Claude nell’ultimo turno
--plugin-dir. Per verificare che il mod sia stato caricato, controlla quali mod ha caricato la sessione.
Per mantenerne uno, aggiungi la directory claude-code/mods del clone come marketplace, quindi installa il mod da claude-code-playground-mods. Il marketplace punta al tuo clone, quindi il mod smette di caricarsi se lo sposti o lo elimini.
Decidere se fidarsi di un mod
Un mod è codice che viene eseguito con i tuoi permessi, all’interno di Claude Code. Installa i mod solo da autori e marketplace di cui ti fidi.A cosa può accedere un mod
Un mod viene eseguito con i tuoi permessi, quindi prima di installarne uno, sappi a cosa ha accesso. Una volta caricato, un mod può:- Agire sulla tua macchina come se fossi tu: leggere e scrivere file ovunque possa farlo il tuo account utente, avviare programmi ed effettuare richieste di rete
- Leggere i tuoi segreti: variabili d’ambiente e file di impostazioni, inclusa una chiave API che conservi in uno dei due
- Vedere la tua sessione: ogni prompt che invii e ogni chiamata a uno strumento che Claude effettua
- Modificare la tua sessione: riscrivere un prompt o una chiamata a uno strumento, inviare un prompt come se lo avessi digitato tu, o inviare un messaggio a un’altra delle tue sessioni
- Agire senza chiederti nulla: approvare una chiamata a uno strumento prima che ti venga chiesto
- Consumare il tuo utilizzo: chiamare un modello sul tuo piano o sulla tua chiave API
deny o ask o i tuoi hook PreToolUse bloccherebbero, a meno che la protezione integrata non lo impedisca. Con la protezione caricata, per impostazione predefinita il mod di un utente non può farlo. In una sessione del terminale locale, cc-plugin-sec-default nella scheda Installed di /plugin indica che la protezione è caricata.
Un mod può modificare lo stile di gran parte dell’interfaccia di Claude Code, ma non della richiesta di permesso. Non può cambiare ciò che la richiesta ti mostra.
Elencare cosa fa un mod prima di installarlo
Prima di installare un mod, puoi elencare quali eventi gestisce e cosa chiede a Claude Code di fare, come leggere un file o effettuare una richiesta di rete, senza eseguirlo. Procurati prima i file del plugin, ad esempio clonando il suo repository. Poi, nella tua shell, eseguiclaude plugin validate sulla directory del plugin:
hooks: e calls: nell’output elencano gli eventi che il mod gestisce e cosa chiede a Claude Code di fare. Esaminare cosa può fare un mod mostra l’output e quali chiamate cercare.
Attivare o disattivare i mod
I mod sono attivi per impostazione predefinita. Nel terminale, usa Claude Code v2.1.287 o versioni successive. L’app Desktop include una propria copia di Claude Code e i mod funzionano lì a partire dalla v2.1.286. Controlla la versione nel punto in cui usi i mod:- Terminale: nella tua shell, esegui
claude --version. Se la tua versione è precedente, aggiorna Claude Code. - App Desktop: in una sessione locale nella scheda Code, inserisci
/statuse leggi la riga Claude Code, che mostra una versione come2.1.286. Se la tua versione è precedente, aggiorna l’app Desktop.
- Un mod: disabilita o disinstalla il suo plugin dalla scheda Installed in
/plugin - Tutti i mod installati, per una sessione: avvia Claude Code con
--safe-mode, che disabilita anche le tue altre personalizzazioni - Tutti i mod che hai installato, in ogni sessione: imposta
"disableAllHooks": truein~/.claude/settings.json. Si fermano anche i tuoi hook delle impostazioni e la tua riga di stato personalizzata. Ciò che è gestito dalla tua organizzazione continua a funzionare.
disableAllHooks e l’impostazione allowManagedModsOnly della tua organizzazione fermano un mod e lasciano intatto il resto del suo plugin: il plugin resta installato e le sue skill, i suoi comandi, i suoi agenti e i suoi server MCP vengono caricati. Altre impostazioni e altri flag hanno un effetto più ampio. disableAllHooks e Cosa viene eseguito con allowManagedHooksOnly elencano l’effetto di ciascuno su un plugin e sui suoi hook delle impostazioni.
Per scoprire se i mod possono essere caricati nel tuo caso, consulta Verificare se i mod possono essere caricati.
Se hai impostato
CLAUDE_CODE_ENABLE_FUNCTION_HOOKS durante l’accesso anticipato, rimuovila. Claude Code v2.1.287 e versioni successive la ignorano, quindi impostarla su 0 non mantiene disattivati i mod.Vedere quali mod ha caricato una sessione
Per vedere quali mod ha caricato una sessione del terminale, esegui/plugin nel prompt di Claude Code. Una riga attenuata sotto le schede indica il numero e i nomi, ad esempio 1 mod active · first-mod. Se un mod che hai installato non è indicato lì, consulta Scoprire perché un mod non fa nulla.
Come funziona un mod
Un mod è un plugin il cui codice registra dei gestori di eventi, chiamati hook. Claude Code esegue un hook quando si verifica il suo evento, ad esempio quando Claude chiama uno strumento o quando viene disegnato lo spinner. Un mod piccolo ha tre file:plugin.json: il manifest del pluginhooks.json: punta al tuo file di codiceregister.js: il tuo codice, chiamato modulo degli hook. Indica a Claude Code su quali eventi eseguire le tue funzioni.
register.js completo. Conta le chiamate agli strumenti che Claude effettua e mostra il conteggio accanto allo spinner mentre Claude lavora, come in Thinking · tool calls: 3….
hooks/register.js
calls in cima:
- L’hook
tool.callviene eseguito ogni volta che Claude sta per usare uno strumento. Aggiunge uno acalls, chiede a Claude Code di disegnare di nuovo l’interfaccia e lascia che lo strumento venga eseguito come di consueto. - L’hook
ui.renderviene eseguito ogni volta che Claude Code disegna lo spinner. Mantiene lo spinner di Claude Code e aggiunge il conteggio dopo la parola.
Thinking · tool calls: 1…, poi 2…, poi 3….
Cosa può fare un hook con un evento
Claude Code esegue il tuo hook prima di agire sull’evento, quindi è l’hook a decidere cosa succede dopo. Può:- Osservare: prendere nota di ciò che sta accadendo e lasciarlo proseguire invariato, come fa l’hook
tool.callnell’esempio - Riscrivere: modificare l’evento prima che prosegua, come fa l’hook
ui.renderquando aggiunge il conteggio allo spinner - Rispondere: gestire l’evento direttamente, in modo che il comportamento consueto non venga eseguito, ad esempio rifiutando un comando
Dove vengono eseguiti i mod
Gli hook di un mod vengono eseguiti in ogni tipo di sessione che carica il plugin, qualunque sia il provider che fornisce il modello, inclusi Amazon Bedrock, Agent Platform di Google Cloud e Microsoft Foundry. Il disegno è più limitato: ciò che un mod disegna appare nel terminale, nell’app Desktop e nell’estensione VS Code. Questa tabella elenca ogni luogo in cui potresti eseguire Claude Code:
Un mod che disegna può verificare in quale app è in esecuzione e ripiegare su una riga nella trascrizione o sulla risposta testuale di un comando dove nulla viene disegnato.
Controllare i mod per la tua organizzazione
Gli amministratori decidono se i mod vengono eseguiti e quali, tramite le impostazioni gestite. Gestire i mod per la tua organizzazione spiega cosa succede per impostazione predefinita, come esaminare un mod e come applicare una policy con un mod tuo.Confrontare mod, hook delle impostazioni, skill e server MCP
Mod, hook delle impostazioni, skill e server MCP si sovrappongono. Questa tabella mostra cos’è ciascuno e quando sceglierlo.
Ciascuno degli altri ha una propria pagina: Hook, Skill e MCP. Un plugin può contenerli tutti, quindi un mod può essere distribuito nello stesso plugin di una skill e di un server MCP.
Mod integrati in Claude Code
Alcune funzionalità di Claude Code sono esse stesse dei mod. Per vedere quelli presenti nella tua sessione, esegui/plugin nel prompt di Claude Code e vai alla scheda Installed, che li elenca sotto Built-in. Non puoi aggiornare o disinstallare un mod integrato. La riga mods active omette i mod integrati.
Questa tabella elenca alcune delle voci Built-in con il nome mostrato da /plugin:
Per un plugin Built-in che non è nella tabella, apri i suoi dettagli in
/plugin per leggere cosa fa o per disabilitarlo.
Le impostazioni e i flag che bloccano i mod installati, come disableAllHooks, --bare e --safe-mode, non bloccano i mod integrati.
Leggi il sorgente dei mod integrati
Il sorgente di alcuni di questi mod è pubblico nella directorymods del repository di Claude Code. Ciascuno è un plugin completo con il suo modulo degli hook e i relativi test:
diff: il pannello di/diff, con pulsanti associati ad azioni da tastiera e uno scorrimento gestito dal mod stessoagents-md: caricaAGENTS.mdcome istruzioni del progetto, con un’opzioneuserConfigsec-default: la protezione descritta in Sapere cosa succede per impostazione predefinita, un modello per un mod che applica delle policytelemetry: aggiunge metodi che altri mod possono chiamare e ne distribuisce i tipi
Passaggi successivi
- Crea un mod: creane uno che conta le chiamate agli strumenti, mostra il conteggio accanto allo spinner e aggiunge un comando, e impara il ciclo di modifica e ricaricamento
- Disegna nell’interfaccia: riquadri, la fascia sopra il prompt, pulsanti, campi di testo e stato
- Reagisci agli eventi: chiamate agli strumenti, prompt, turni e l’ordine in cui vengono eseguiti i mod
- Usa l’API dei mod: comandi, strumenti, chiamate al modello, timer e file
- Testa un mod: test automatizzati che vengono eseguiti senza una sessione
- Risolvi i problemi di un mod: i motivi per cui un mod non fa nulla e il log di debug
- Gestisci i mod per la tua organizzazione: impostazioni predefinite, impostazioni gestite, revisione di un mod e mod di criteri
- Riferimento dei mod: eventi, metodi, elementi e limiti