Panoramica dei mod

Aggiungi pannelli, comandi e regole per le chiamate agli strumenti a Claude Code con un mod. Scopri cosa può fare un mod, come crearne o installarne uno e dove vengono eseguiti i mod.

Un mod è un plugin che cambia l'aspetto e il comportamento di Claude Code. È composto da gestori di eventi JavaScript o TypeScript: Claude Code ne chiama uno quando si verifica un evento, come una chiamata a uno strumento, un prompt inviato o il disegno di una parte dell'interfaccia, e il gestore può osservare l'evento, modificarlo o prenderne il controllo. Usa un mod per aggiungere a Claude Code una funzionalità tutta tua, come un pannello che mostra in un grafico quanto è pieno il tuo contesto dopo ogni richiesta. Per i file di un mod e un esempio completo, consulta Come funziona un mod.

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 /command che 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.

I mod funzionano nella CLI di Claude Code e nella scheda Code dell'app Claude Desktop. Consulta Dove vengono eseguiti i mod per capire come si comportano altrove, ad esempio nell'estensione VS Code, in 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.

Installa plugin tratta i marketplace, gli ambiti, l'estensione VS Code e l'app Desktop, e come mantenere aggiornati i plugin: tutto ciò si applica senza modifiche a un plugin che contiene un mod.

Se installi o aggiorni un mod dalla tua shell mentre una sessione è aperta, esegui /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 directory claude-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 prompt
• blast-radius: trattiene un comando di shell rischioso, come rm -rf o un force push, e mostra cosa modificherebbe, con pulsanti per procedere o annullare
• replay-theater: aggiunge un comando /replay che ripercorre passo per passo le modifiche ai file effettuate da Claude nell'ultimo turno

Un mod di esempio viene eseguito con i tuoi permessi. Per vedere cosa fa prima di caricarlo, elenca i suoi hook e le sue chiamate.

Per provarne uno, clona il repository e carica la directory del mod per una sessione con --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

I mod non sono eseguiti in una sandbox. Se attivi il sandboxing, la sandbox isola i comandi Bash che Claude esegue, mentre un processo avviato da un mod viene eseguito al di fuori di essa.

Un mod che approva le chiamate agli strumenti può approvarne una per cui una regola ask chiederebbe conferma, o che uno dei tuoi hook PreToolUse ha bloccato. Estendere i permessi con gli hook elenca cosa può approvare un mod di questo tipo, incluso quando può approvare una chiamata che una regola deny rifiuta.

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, esegui claude plugin validate sulla directory del plugin:

claude plugin validate ./some-mod

Le righe 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 /status e leggi la riga Claude Code, che mostra una versione come 2.1.286. Se la tua versione è precedente, aggiorna l'app Desktop.

Per disattivare i mod, scegli quanti fermarne e per quanto tempo. Per riattivarli, annulla la stessa modifica:

• 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": true in ~/.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.

Se usi Claude Code tramite un'organizzazione, anche un amministratore può limitare quali mod vengono caricati. Gli amministratori possono iniziare da Impedire il caricamento dei mod installati dagli utenti.

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.

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:

first-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

• plugin.json: il manifest del plugin
• hooks.json: punta al tuo file di codice
• register.js: il tuo codice, chiamato modulo degli hook. Indica a Claude Code su quali eventi eseguire le tue funzioni.

Questo è un 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….

// The count, shared by the two hooks below
let calls = 0

// Claude Code calls this once when the mod loads
export function register(on) {
  // Runs each time Claude is about to use a tool
  on('tool.call', async ($, e, next) => {
    calls += 1
    // Ask Claude Code to draw the interface again, so the new count shows
    $.ui.invalidate('ui.render')
    // Let the tool run as usual
    return next(e)
  })

  // Runs each time Claude Code draws the spinner
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    // Keep Claude Code's spinner, with the count added after its word
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
  })
}

Il file registra due hook, ed entrambi usano la variabile calls in cima:

• L'hook tool.call viene eseguito ogni volta che Claude sta per usare uno strumento. Aggiunge uno a calls, chiede a Claude Code di disegnare di nuovo l'interfaccia e lascia che lo strumento venga eseguito come di consueto.
• L'hook ui.render viene eseguito ogni volta che Claude Code disegna lo spinner. Mantiene lo spinner di Claude Code e aggiunge il conteggio dopo la parola.

Questa registrazione mostra il mod in azione. Osserva la riga dello spinner sopra la casella del prompt: mentre Claude elenca una directory e legge due file, mostra Thinking · tool calls: 1…, poi 2…, poi 3….