Mod di Claude Code: cosa sono e quello che forniamo a ogni agente

Il 1º ottobre 2026 Claude Code 2.1.287 è uscito con una sola riga nel changelog: "Added Claude Mods". Quattro giorni dopo, AgentsRoom ha iniziato a caricare uno dei nostri negli agenti Claude che esegue.

Questo articolo spiega cos'è un mod, cosa può fare che i punti di estensione precedenti non potevano, come scriverne, caricarne e testarne uno, e cosa abbiamo imparato fornendo un mod a ogni agente Claude avviato da AgentsRoom. Le informazioni su Claude Code vengono dalla sua documentazione e dal suo changelog, consultati il 9 novembre 2026, con Claude Code 2.1.318 installato.

La risposta breve. Un mod è un plugin di Claude Code con un hooks module: un file JavaScript o TypeScript le cui funzioni vengono chiamate da Claude Code dall'interno del suo stesso processo quando si verifica un evento. Una funzione può lasciar passare l'evento, modificarlo o rispondere al posto di Claude Code. È così che un mod disegna un pannello, aggiunge un comando o ferma un comando shell prima che venga eseguito.

Cos'è un mod

Claude Code aveva già i plugin: una cartella con un manifest in .claude-plugin/plugin.json che raccoglie skill, subagenti, hook di settings e server MCP perché si installino come un'unica unità. Un mod è una cosa in più che un plugin può contenere. Quando il hooks/hooks.json del plugin indica un file di codice sotto la sua chiave modules, Claude Code carica quel file e chiama la funzione register che esporta. A quel punto il plugin si chiama mod.

Dentro register, ogni chiamata a on(event, hook) collega una funzione a un evento: tool.call prima che uno strumento venga eseguito, prompt.submit quando invii un prompt, session.start, command.run per un comando slash, ui.render quando Claude Code disegna una parte del suo schermo, e altri. Ogni hook riceve tre cose:

• $, l'API dei mod: tutto quello che un mod può fare fuori dal proprio codice, come $.ui, $.command, $.fs, $.process o $.http.
• e, l'evento, come dati semplici: per una chiamata a uno strumento, il nome dello strumento e i suoi argomenti.
• next, che passa l'evento agli altri mod e poi al comportamento di Claude Code stesso, e restituisce il risultato.

Quello che l'hook fa con next decide cosa succede. Restituisci next(e) e ti sei limitato a osservare. Chiama next con una copia modificata di e e hai riscritto l'evento. Restituisci un tuo risultato senza chiamare next e hai risposto tu: lo strumento non viene mai eseguito, oppure Claude Code non disegna mai la sua parte.

Anche la documentazione chiama hook queste funzioni. Non sono gli hook che scrivi in settings.json, che Claude Code ora chiama settings hooks.

Mod, hook di settings, skill o server MCP

I quattro si sovrappongono, e il mod è il più pesante. Scegli il più leggero che fa il lavoro.

Un plugin può contenere tutti e quattro, quindi un mod può essere distribuito accanto alla skill e al server MCP con cui lavora.

I tre file di un mod

my-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.ts

plugin.json è il solito manifest di un plugin: un nome, una versione, una descrizione. hooks.json punta al codice, { "modules": ["./register.ts"] }, un solo percorso relativo a quel file. register.ts è l'hooks module. Claude Code carica direttamente .js e .ts, senza bundler e senza fase di build, e l'unico import senza percorso consentito è claude-code, per i tipi e qualche funzione di utilità.

Il mod che forniamo: chi ha modificato questo file?

AgentsRoom esegue più agenti di codice sullo stesso repository e mostra, nella sua scheda Modifiche, quale agente ha modificato quale file, così puoi rivedere e committare il lavoro di ogni agente separatamente. I file scritti con gli strumenti Edit e Write di Claude erano facili: Claude Code li segnala tramite un hook di settings. Quelli scritti da un comando shell no. Un sed -i, un heredoc, un codemod o un rm non passano mai da uno strumento per i file.

Prima dei mod, andavamo a intuito. AgentsRoom leggeva la trascrizione della sessione dell'agente per sapere quando ogni comando Bash era iniziato e finito, poi confrontava la data di modifica del file con quegli intervalli. Funzionava quasi sempre e falliva in tre modi che sapevamo nominare:

• un file eliminato non ha data di modifica, quindi un'eliminazione non veniva mai attribuita;
• un comando in sola lettura come grep apriva un intervallo durante il quale l'agente avrebbe potuto scrivere qualsiasi cosa;
• tutto dipendeva dal formato della trascrizione, che Claude Code è libero di cambiare.

Un mod elimina l'ipotesi. Il nostro mod agentsroom-changes si aggancia a tool.call per i due strumenti shell. Subito prima che il comando venga eseguito, scatta un'istantanea del repository (git status più dimensione e data di modifica di ogni percorso modificato). Subito dopo, ne scatta una seconda. I percorsi che differiscono sono ciò che quel comando ha cambiato, eliminazioni comprese, e il mod li invia all'app desktop di AgentsRoom tramite un endpoint HTTP locale. Una chiamata che Claude Code stesso segnala come in sola lettura non rivendica nulla.

Ecco l'hook, accorciato. Il file completo è di 177 righe, la maggior parte per l'istantanea e i suoi limiti.

import type { Register } from 'claude-code';

const SHELL_TOOLS = new Set(['Bash', 'PowerShell']);

export const register: Register = (on) => {
  on('tool.call', async ($, e, next) => {
    if (!SHELL_TOOLS.has(e.tool)) return next(e);
    const ready = await prepare($).catch(() => null); // agent id, repo root, snapshot
    if (!ready) return next(e);                        // outside AgentsRoom: do nothing
    const callId = e.tool_use_id;
    post($, ready.agentId, { kind: 'start', callId });
    const ran = await next(e);                         // the command runs here
    const wroteNothing = ran.deny !== undefined || ran.isReadOnly === true;
    await reportEnd($, { ...ready, callId }, wroteNothing)
      .catch(() => post($, ready.agentId, { kind: 'end', callId, paths: [] }));
    return ran;                                        // Claude sees the normal result
  });
};

L'app desktop copia il mod nella propria cartella e avvia ogni agente Claude con claude --plugin-dir <that folder>, solo quando il Claude Code installato è la 2.1.287 o successiva. L'abbiamo rilasciato in AgentsRoom 1.201.0 il 5 ottobre 2026.

Cosa abbiamo imparato rilasciandolo

Un mod non deve mai costare all'utente una chiamata a uno strumento. Il nostro hook sta davanti a ogni comando shell che Claude esegue. Se genera un errore, o resta in attesa della rete, il lavoro di Claude si ferma. Ogni passaggio è protetto, ogni invio all'app desktop parte senza attendere risposta, e l'unica attesa che accettiamo sono due istantanee git status, limitate a 15 secondi ciascuna. Un invio perso costa un'attribuzione, mai il comando.

Non fare nulla quando nessuno ti ha chiamato. Il mod legge una variabile d'ambiente che AgentsRoom imposta per i suoi agenti. Quando manca, per esempio perché qualcuno ha copiato la cartella nella propria configurazione, ogni hook passa direttamente a next(e).

Una cartella caricata con --plugin-dir è sorvegliata. Claude Code ricarica il mod quando cambia un file in quella cartella, e un ricaricamento esegue di nuovo register. Questo ha deciso come lo installiamo: l'app desktop scrive un file del mod solo quando il suo contenuto è cambiato, perché riscriverlo alla cieca a ogni avvio di un agente ricaricherebbe il mod in tutte le console Claude già aperte.

Metti in conto che l'API cambi. Eventi e metodi possono cambiare da una versione all'altra, e lo dice la documentazione stessa. Quando un mod viene caricato da --plugin-dir, Claude Code scrive le dichiarazioni dei tipi della versione in esecuzione in .claude-plugin/types/; facciamo il controllo dei tipi su quelle, non su una pagina web. E se una build non carica più il nostro mod, non si rompe nulla: il mod non si dichiara mai pronto, e AgentsRoom torna al vecchio metodo della trascrizione.

Scrivi il tuo

Hai due strade.

Chiedilo a Claude. In una sessione interattiva di Claude Code, descrivi il mod che vuoi ("mostra il branch git corrente sopra il prompt"). Claude usa una skill integrata, plugin-authoring, scrive il mod in una cartella per quella sessione, e Claude Code ti chiede una sola volta se vuoi attivare i mod scritti da Claude. Rispondi di sì e il mod si carica alla fine del turno, poi si ricarica dopo ogni turno che lo modifica.

Scrivi tu i tre file, poi:

claude --plugin-dir ./my-mod       # load it for one session, hot reload on save
claude plugin validate ./my-mod    # what Claude Code reads from it, without running it
claude plugin test                 # run the mod's *.test.ts files, no session needed

claude plugin validate stampa una riga hooks: con gli eventi gestiti dal tuo modulo e una riga calls: con ogni metodo dell'API dei mod che chiama. Se manca un evento che volevi gestire, nemmeno Claude Code chiamerà quell'hook. L'analisi statica ha le sue regole: scrivi ogni chiamata per intero ($.ui.toast(...), mai const ui = $.ui), passa i nomi degli eventi come stringhe letterali, e importa solo i tuoi file tramite percorso relativo.

Per condividere un mod, trattalo come il plugin che è: invia la cartella, oppure pubblicalo in un marketplace (un repository con un .claude-plugin/marketplace.json) così le persone lo installano con /plugin install <name>@<marketplace>.

Mod che puoi leggere oggi

• Integrati in Claude Code: /plugin, scheda Installed, sezione Built-in. Tra questi, il pannello /diff e il caricatore che legge AGENTS.md come istruzioni del progetto, il cui codice Anthropic pubblica nella cartella mods del repository anthropics/claude-code, con i relativi test. Anche questo integrato, e spento finché non lo attivi: You should know, un agente laterale che segnala ciò che a te o a Claude potrebbe essere sfuggito.
• Gli esempi di Anthropic, nel repository claude-code-playground: una previsione della finestra di contesto disegnata sopra il prompt, una protezione che trattiene un comando shell rischioso e mostra cosa cambierebbe, e un comando /replay che ripercorre passo per passo le modifiche dell'ultimo turno.
• Il nostro, descritto sopra: un mod senza alcuna interfaccia, un solo hook tool.call, una buona forma da copiare se ciò che ti serve sono dati e non un pannello.

Prima di installare il mod di qualcun altro

Un mod non è isolato in una sandbox. Viene eseguito con i tuoi permessi: può leggere e scrivere i tuoi file, leggere le tue variabili d'ambiente e le tue impostazioni (chiavi API comprese), avviare programmi, fare richieste di rete, vedere ogni prompt e ogni chiamata a uno strumento, e approvare una chiamata a uno strumento prima che ti venga chiesto. Se hai attivato la sandbox di Claude Code, questa copre i comandi Bash che Claude esegue, non i processi avviati da un mod.

Quindi leggi prima di installare. Clona il mod ed esegui claude plugin validate sulla cartella: le righe hooks: e calls: ti dicono cosa ascolta e cosa raggiunge, senza eseguire nulla. Un mod che disegna solo una fascia sopra il prompt non ha alcun motivo di chiamare $.http o $.process. Per fermare tutti i mod che hai installato, avvia con --safe-mode per una sessione, oppure imposta "disableAllHooks": true in ~/.claude/settings.json.

Dove funzionano i mod

Un mod che disegna dovrebbe verificare dove viene eseguito e ripiegare sul testo dove non si disegna nulla.

Dentro AgentsRoom

Non installi nulla: da Claude Code 2.1.287, ogni agente Claude parte con il mod, e la scheda Modifiche mostra i file che ciascuno dei suoi comandi shell ha creato, modificato o eliminato, accanto all'agente che l'ha fatto. Con un Claude Code più vecchio, AgentsRoom continua ad attribuire le scritture shell a partire dalla trascrizione, come prima.

La stessa idea funziona in altre CLI quando è possibile: oh-my-pi riceve un'estensione con lo stesso contratto, e le altre CLI continuano ad attribuire le scritture shell come facevano prima. Se vuoi andare oltre con ciò che Claude Code espone a ogni passaggio, la nostra guida agli hook di Claude Code copre gli hook di settings accanto ai quali si colloca un mod.

Domande frequenti

Cos'è un mod in Claude Code?

Un mod è un plugin di Claude Code che contiene un hooks module: un file JavaScript o TypeScript le cui funzioni vengono chiamate da Claude Code dall'interno del suo stesso processo quando succede qualcosa, come una chiamata a uno strumento, un prompt inviato o una parte dello schermo da disegnare. Ogni funzione può lasciar passare l'evento, modificarlo o gestirlo da sé. È questo che permette a un mod di disegnare un pannello, aggiungere un comando o trattenere un comando shell rischioso.

Quale versione di Claude Code serve per i mod?

Claude Code 2.1.287 o successiva nel terminale, uscita il 1º ottobre 2026, il cui changelog dice "Added Claude Mods". La scheda Code dell'app Claude Desktop li supporta dalla 2.1.286. Nell'estensione di VS Code gli hook vengono eseguiti, e ciò che un mod disegna richiede l'estensione 2.1.299 o successiva. Esegui claude --version per verificarlo.

Qual è la differenza tra un mod e un hook di Claude Code?

Un hook in settings.json esegue un comando shell, una richiesta HTTP o un prompt quando scatta un evento, fuori da Claude Code. Gli hook di un mod sono funzioni eseguite dentro Claude Code. Possono fare quello che un hook di settings non può: disegnare nell'interfaccia, aggiungere un comando slash che viene eseguito senza un turno di Claude, riscrivere una chiamata a uno strumento o rispondervi senza eseguire lo strumento, e condividere uno stato tra hook.

I mod di Claude Code sono sicuri da installare?

Un mod non è isolato in una sandbox. Viene eseguito con i tuoi permessi, può leggere i tuoi file e le tue variabili d'ambiente, avviare programmi, fare richieste di rete e approvare una chiamata a uno strumento. Installa solo mod di autori di cui ti fidi, e prima esegui claude plugin validate sulla cartella: elenca gli eventi che il mod ascolta e le chiamate che fa, senza eseguirlo.

Dove trovo esempi di mod di Claude Code?

Anthropic pubblica il codice di alcuni mod integrati, come il pannello /diff e il caricatore di AGENTS.md, nella cartella mods del repository anthropics/claude-code, e mod di esempio nel repository anthropics/claude-code-playground. Quello di AgentsRoom descritto in questo articolo è un quarto tipo di esempio: un mod senza interfaccia, con un solo hook tool.call.

Posso disattivare i mod?

Sì. Disattiva un singolo mod dalla scheda Installed di /plugin, avvia una sola sessione con --safe-mode, oppure imposta disableAllHooks a true in ~/.claude/settings.json per fermare tutti i mod che hai installato, insieme ai tuoi hook di settings. --safe-mode e disableAllHooks lasciano attivi i mod integrati: quelli si spengono uno per uno in /plugin.