Claude Code mods: cosa sono e come cambiano comportamento e interfaccia dell'agente

Fino a settembre, personalizzare Claude Code voleva dire lavorare attorno allo strumento: un hook che esegue uno script quando Claude usa un tool, una skill con istruzioni da seguire, un server MCP che aggiunge strumenti nuovi. Con la versione 2.1.287, rilasciata il 1° ottobre 2026, Anthropic ha aperto anche l'interno. I mod sono funzioni JavaScript o TypeScript che girano nel processo di Claude Code e possono osservare, modificare o sostituire quello che l'agente sta per fare, compresa l'interfaccia che disegna nel terminale.

È un cambiamento che riguarda sia chi usa Claude Code ogni giorno sia chi deve decidere cosa può girare sui computer di un team, perché un mod ha molto più potere di un hook o di una skill.

Cos'è un mod

Tecnicamente un mod è un plugin. Contiene un file di codice, chiamato hooks module, che registra delle funzioni su eventi interni di Claude Code: una chiamata a un tool, un prompt inviato, una richiesta di permesso, una parte dell'interfaccia che sta per essere disegnata. Quando l'evento si verifica, Claude Code chiama la funzione prima di agire, e la funzione decide cosa succede. Può limitarsi a registrare l'evento e lasciarlo proseguire, modificarlo, oppure gestirlo da sola al posto del comportamento previsto. Secondo l'annuncio di Anthropic può anche avvolgerlo, eseguendo codice sia prima sia dopo.

Un mod minimo è composto da tre file: il manifest del plugin, un hooks.json che indica dove si trova il codice e il codice vero e proprio.

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

Il file di codice esporta una funzione register che riceve on, il metodo con cui ci si aggancia agli eventi. Questo esempio conta le chiamate ai tool e scrive ognuna nel log di debug, poi lascia che il tool venga eseguito normalmente:

let count = 0

export function register(on) {
  on('tool.call', async ($, e, next) => {
    count += 1
    $.ui.log('tool call #' + count + ': ' + e.tool, { to: 'debug' })
    return next(e)
  })
}

Ogni hook riceve tre argomenti: $, cioè l'API dei mod, l'evento e next, la funzione che passa l'evento agli altri mod e infine a Claude Code. Tutto quello che esce dal codice del mod, come leggere un file, avviare un processo, fare una richiesta di rete o disegnare qualcosa, passa da $. È anche il motivo per cui Claude Code può elencare cosa fa un mod prima di installarlo.

I mod si installano come qualsiasi plugin, da un marketplace, con /plugin install nome@marketplace dentro una sessione oppure con claude plugin install dalla shell. Dalla 2.1.287 sono attivi di default.

Cosa può fare

Dalla documentazione e dall'annuncio di Anthropic emergono due famiglie di interventi. La prima riguarda il comportamento dell'agente:

• riscrivere un prompt prima che arrivi al modello;
• bloccare, riscrivere o ripetere una chiamata a un tool, oppure sospenderla mentre si chiede qualcosa all'utente;
• approvare o negare una richiesta di permesso;
• togliere segreti dall'output di un tool prima che Claude lo legga;
• aggiungere un comando /qualcosa che esegue codice subito, senza avviare un turno di Claude, anche mentre l'agente sta lavorando;
• inviare una richiesta a un modello diverso.

La seconda riguarda l'interfaccia, ed è la parte più nuova. Un mod può aprire un pannello accanto alla conversazione o una fascia sopra il prompt, con schede, pulsanti e campi di testo. Può anche modificare elementi che Claude Code disegna da sé, come lo spinner, la riga di una chiamata a un tool o la finestra con cui Claude pone domande. L'unica eccezione dichiarata è il prompt dei permessi: un mod non può cambiare quello che mostra.

Le funzioni di uno stesso mod condividono le variabili del file, quindi un hook può raccogliere dati e un altro mostrarli. È lo schema dell'esempio più semplice della documentazione, che conta le chiamate ai tool e aggiunge il numero accanto allo spinner.

Più mod possono agganciarsi allo stesso evento. Vengono eseguiti nell'ordine in cui sono caricati: il primo vede l'evento per primo e il risultato per ultimo, e questo permette di combinare mod di autori diversi.

Mod, hook, skill e server MCP

I mod non sostituiscono gli altri meccanismi di estensione, che restano supportati e hanno scopi diversi. Gli hook configurati nei file di impostazioni, che la documentazione ora chiama settings hook per distinguerli, continuano a funzionare accanto ai mod.

• Mod. Cos'è: funzioni eseguite dentro il processo di Claude Code. Cosa cambia: tool call, prompt, comandi, turni e interfaccia. Si scrive in: JavaScript o TypeScript.
• Settings hook. Cos'è: comando shell, richiesta HTTP o prompt eseguito su un evento. Cosa cambia: se un tool call o un prompt procede, gli argomenti e il risultato di un tool, il contesto aggiunto. Si scrive in: uno script e una voce in settings.json.
• Skill. Cos'è: un file SKILL.md di istruzioni che Claude legge. Cosa cambia: cosa Claude sa e come lavora. Si scrive in: Markdown.
• Server MCP. Cos'è: un processo o servizio esterno. Cosa cambia: quali strumenti ha Claude. Si scrive in: qualsiasi linguaggio.

Dei quattro, solo il mod può disegnare nell'interfaccia. Se però serve soltanto bloccare o registrare un evento con uno script già pronto, un settings hook è più semplice; se il problema è dare a Claude le stesse istruzioni ogni volta, basta una skill. Un plugin può contenere tutti e quattro.

Dove funzionano

Gli hook di un mod girano in tutte le sessioni che caricano il plugin. Il disegno ha un perimetro più stretto: pannelli, fasce ed elementi sostituiti compaiono solo nel terminale (compreso quello integrato in un editor e il plugin JetBrains) e nella scheda Code dell'app desktop.

Nell'estensione per VS Code, con claude -p, con l'Agent SDK e nelle sessioni cloud la logica funziona ma l'interfaccia del mod non si vede. Nelle sessioni WSL dell'app desktop i plugin non sono disponibili, quindi i mod non vengono caricati affatto. Chi scrive un mod che disegna può verificare in quale ambiente si trova e ripiegare su una riga nella conversazione.

I mod già presenti e come iniziare

Alcune funzioni di Claude Code sono già diventate mod. Il comando /diff, per esempio, è ora gestito da un mod integrato che si può disattivare da /plugin o sostituire con una versione propria. Gli altri mod integrati caricano AGENTS.md come istruzioni di progetto, inviano i dati di telemetria e, nelle organizzazioni, fanno da guardia contro i mod installati dagli utenti. Il codice di diff, agents-md, sec-default e telemetry è pubblico nella cartella mods del repository anthropics/claude-code. Anthropic ha scritto di voler trasformare in mod altre funzioni nel tempo, per arrivare a un nucleo ridotto a cui ciascuno aggiunge solo ciò che gli serve.

Per vedere cosa si può costruire, Anthropic pubblica tre mod di esempio nel repository claude-code-playground, distribuiti così come sono e senza supporto:

• token-weather disegna sopra il prompt una previsione di quanto si sta riempiendo la finestra di contesto;
• blast-radius trattiene un comando shell rischioso, come rm -rf o un force push, mostra cosa cambierebbe e chiede se procedere;
• replay-theater aggiunge un comando /replay che ripercorre le modifiche ai file fatte da Claude nell'ultimo turno.

Il modo più rapido per scriverne uno è chiederlo a Claude Code. Claude scrive il codice in una cartella dedicata alla sessione dentro ~/.claude/dev-mods/, chiede conferma prima di creare i file e propone di attivare il ricaricamento a caldo, così il mod funziona subito senza riavviare. Un mod creato in questo modo resta legato a quella sessione: per usarlo altrove va spostato in una cartella propria e caricato come plugin.

Chi preferisce scriverlo a mano trova nella documentazione il riferimento completo di eventi, metodi ed elementi grafici, insieme a un kit per testare i mod senza aprire una sessione.

Sicurezza: cosa controllare prima di installare un mod

Un mod non è isolato in una sandbox. Gira con gli stessi permessi dell'utente e, una volta caricato, può leggere e scrivere file ovunque l'account abbia accesso, avviare programmi, fare richieste di rete, leggere variabili d'ambiente e file di impostazioni (comprese eventuali chiavi API), vedere ogni prompt e ogni tool call, inviare prompt come se li avesse scritti l'utente e consumare il piano o la chiave API chiamando un modello. Anche con il sandboxing di Claude Code attivo, un processo avviato da un mod resta fuori dalla sandbox. Anthropic lo dice in modo esplicito: i mod vanno installati solo da autori e marketplace di cui ci si fida, come qualsiasi altro codice.

C'è un punto meno evidente. Un mod che approva le tool call può approvarne una che una regola ask avrebbe sottoposto all'utente, o che un hook PreToolUse dell'utente aveva bloccato. In auto mode una chiamata approvata dal mod parte senza il controllo del classificatore.

Prima di installare un mod si può vedere cosa fa senza eseguirlo. Basta scaricare i file del plugin e lanciare dalla shell:

claude plugin validate ./nome-mod

La riga hooks dell'output elenca gli eventi a cui il mod si aggancia, la riga calls i metodi dell'API che usa. Le chiamate da guardare con più attenzione sono quelle su file system, processi, rete, variabili d'ambiente e modelli. Claude Code rifiuta di caricare un mod che usa l'API in un modo che questo controllo non riesce a leggere.

Per spegnere i mod ci sono tre livelli: disattivare il singolo plugin da /plugin, avviare una sessione con --safe-mode, che disattiva tutti i mod installati insieme alle altre personalizzazioni, oppure impostare "disableAllHooks": true in ~/.claude/settings.json, che ferma anche i settings hook e la status line personalizzata. I mod integrati non vengono toccati da queste impostazioni.

Nei team e nelle aziende

Sui piani Team ed Enterprise, e su qualsiasi macchina con impostazioni gestite, Claude Code carica per primo il mod integrato sec-default, che l'utente non può disattivare. Impedisce ai mod installati dagli utenti di aggirare le regole deny e gli hook gestiti dall'organizzazione, o di modificare istruzioni, impostazioni e server MCP gestiti. Il resto resta consentito: un mod dell'utente può ancora leggere file, avviare processi e riscrivere tool call con i permessi di quell'utente.

Chi amministra può restringere ulteriormente. L'opzione allowManagedModsOnly, impostata nelle impostazioni gestite, impedisce il caricamento di qualsiasi mod portato dagli utenti, compresi quelli scritti da Claude durante una sessione. Le regole che limitano i marketplace da cui installare plugin valgono anche per i mod. Un'organizzazione può inoltre distribuire mod propri e farli eseguire prima di quelli degli utenti: l'annuncio di Anthropic cita come esempi un pannello con lo stato della pipeline CI/CD, una conferma obbligatoria prima di qualsiasi comando che tocchi la configurazione di produzione e un mod che registra ogni chiamata fatta dagli altri mod.

Fonti

1. Anthropic. “Customize Claude Code with mods”. 1° ottobre 2026.
2. Anthropic. “Mods overview”, documentazione di Claude Code. Consultata il 6 ottobre 2026.
3. Anthropic. “Manage mods for your organization”, documentazione di Claude Code. Consultata il 6 ottobre 2026.
4. Anthropic. “Criar um mod (Create a mod)”, documentazione di Claude Code, versione in portoghese. Consultata il 6 ottobre 2026.
5. Anthropic. “Mappa della documentazione di Claude Code (sezione Mods)”. Aggiornata al 6 ottobre 2026.