Claude Code Mod non funziona: caricamento, hot reload e stato

Se un Claude Code Mod non funziona o perde stato durante l’hot reload, parti dal sintomo e dal messaggio reale. Installazione, caricamento del modulo, esecuzione dell’handler e disegno della UI sono passaggi diversi. Reinstallare tutto prima di distinguerli può nascondere la causa e creare copie non confrontabili. La guida ufficiale di troubleshooting descrive questi livelli.

Questa procedura è verificata il 9 ottobre 2026. Serve a costruire una diagnosi riproducibile, senza inventare il risultato di una macchina a cui non abbiamo accesso. Per orientarti nell’architettura leggi cosa sono i Mods; se il problema è soltanto l’aggiornamento di una copia installata, parti da installazione e reload.

Qual è il sintomo esatto del mod che non funziona?

Scrivi il comportamento atteso e quello osservato in due frasi. «Il plugin è rotto» non basta. «Il comando non compare nell’elenco» porta a registrazione e caricamento. «Il comando compare ma restituisce un valore vecchio» porta a stato o dato. «Il valore cambia ma il pannello manca» porta alla superficie e al render. Il primo bivio riduce il numero di ipotesi.

Indica anche cosa è cambiato immediatamente prima: aggiornamento, reload, nuova sessione, spostamento di directory o modifica del codice. Non assumere che il cambiamento più recente sia per forza la causa, ma usalo per preparare un confronto. Una diagnosi utile cerca differenze controllabili fra prima e dopo, non un elenco casuale di possibili problemi.

Conserva una riproduzione minima: un ingresso, una risposta e un cambiamento. Se il difetto compare soltanto dopo una lunga sessione, prova a identificare l’evento che lo rende osservabile. Ridurre il caso non significa ridurre il problema dell’utente; significa renderlo verificabile prima di cambiare codice.

Versione, policy e rollout: come separarli?

Controlla la versione effettiva di Claude Code. Le guide operative indicano 2.1.287 o successiva, ma una funzione recente può richiedere altro. La reference online non aggiorna la tua installazione. Per i mod sviluppati localmente confronta il codice con i tipi generati dalla build che usi. Guida di creazione.

Poi leggi la policy. disableAllHooks, modalità di avvio e impostazioni organizzative possono impedire il caricamento del modulo. Un messaggio di rifiuto è più utile di un tentativo di aggiramento. Se la macchina è gestita, conserva il motivo per il responsabile e completa le verifiche di codice che non dipendono dal cambiamento della policy.

La documentazione segnala anche un rollout remoto che può disattivare Mods installati e valori salvati da sessioni precedenti. Non dedurre che sia accaduto nel tuo caso soltanto perché la possibilità esiste. Il messaggio deve corrispondere al sintomo. Una sessione nuova può aggiornare quello stato secondo la guida, ma non sostituisce l’analisi del motivo riportato.

Dove cercare la prova del caricamento?

Il pannello /plugin permette di consultare lo stato del plugin; la riga mods active aiuta a riconoscere quali moduli sono effettivamente attivi. Nel log di debug il motivo può comparire dopo hooks module, nome del mod e not loaded:. La guida di diagnosi descrive questa lettura.

Non confondere la presenza del pacchetto con l’esecuzione di ogni parte. Alcune impostazioni possono lasciare disponibili altri componenti mentre il modulo non viene caricato. Il fatto che una Skill del plugin compaia non prova che il suo mod sia attivo. Questa distinzione è utile quando una confezione include più capacità e il sintomo riguarda solo una di esse.

Per raccogliere log usa il percorso documentato di claude --debug soltanto nel tuo ambiente controllato. Conserva l’estratto necessario, eliminando contenuti sensibili prima di condividerlo. Il report dovrebbe indicare motivo, evento e versione; non richiede l’intera conversazione o una copia del repository cliente. Leggi anche AI e sicurezza dei dati prima di esportare diagnostica.

La validazione passa ma il modulo non fa nulla: perché?

Un risultato di validazione va letto, non soltanto cercato nella sua ultima riga. La guida di creazione mostra informazioni sugli eventi e sulle chiamate riconosciute. Se manca l’evento che volevi gestire, il caricatore non avrà il comportamento atteso. Un nome errato o una registrazione non riconoscibile possono essere scoperti prima della sessione.

Controlla anche il collegamento modules di hooks/hooks.json e l’export del file di ingresso. Un manifest valido non basta se il percorso punta a un file diverso. La reference dei comandi plugin distingue questa analisi dai test di comportamento. La domanda è cosa il prodotto legge dal modulo, non cosa l’autore immaginava di aver registrato.

Se la struttura è corretta, prepara un evento sintetico e un’aspettativa. La guida a testare un mod aiuta a verificare il percorso senza una chiamata al modello. Un caso piccolo permette di separare l’handler difettoso dal resto dell’ambiente e riduce il rischio di modificare componenti che funzionano.

Hai aggiornato la copia giusta?

Identifica origine, versione, scope e percorso. Una directory caricata con --plugin-dir e una copia installata da marketplace possono avere lo stesso nome ma contenuti diversi. Un collega può osservare un comportamento corretto nella directory di sviluppo mentre la sessione abituale continua a usare il pacchetto precedente.

Per i plugin custom controlla che la versione sia stata incrementata prima della distribuzione. Per la sessione controlla se il reload è stato applicato o se serve una nuova sessione. Non modificare direttamente la cache per far coincidere due macchine: correggi il percorso di distribuzione. La guida a installazione e aggiornamento tratta questi tre livelli.

Un comportamento distintivo aiuta a verificare la versione senza fare operazioni rischiose. Può essere una descrizione del comando o una risposta su fixture. Non aggiungere log con dati clienti solo per capire quale copia risponde. Una diagnostica progettata dovrebbe rendere riconoscibile il componente, non esportare tutto ciò che vede.

La UI manca anche se il comando funziona?

Questo sintomo sposta la diagnosi dalla registrazione alla presentazione. Controlla quale superficie usi e quale punto il mod disegna. Terminale, desktop e altre forme di esecuzione non hanno capacità UI identiche. Un handler attivo può quindi funzionare senza mostrare il componente previsto. Superfici Mods.

Controlla poi filtri del render, props e spazio disponibile. Una banda può essere occupata da un’altra personalizzazione. Un pannello può richiedere un layout differente. Non cambiare la fonte dei dati se il comando dimostra che il valore è già corretto: prima verifica dove e come viene rappresentato.

Le demo offrono casi chiari. Token Weather ha una banda con cadenza propria; Replay Theater ha una vista temporanea del turno. Se usi una superficie diversa da quella dichiarata, il primo problema è il contratto d’uso, non necessariamente un bug nel codice.

Perché l’hot reload perde stato?

Una variabile di modulo viene ricreata al reload. La documentazione distingue questa durata da $.state, che sopravvive al reload nel ciclo di vita della sessione, e da $.store, persistente su disco. Stato e store rispondono a bisogni diversi; la persistenza non è un miglioramento automatico. Interfaccia e stato Mods.

Le operazioni di fine sessione, clear, resume o branch possono azzerare lo stato secondo il ciclo documentato. Lo store ha a sua volta un rapporto con la pulizia per inattività. Se il requisito è conservare una preferenza a lungo, scrivilo esplicitamente. Se il requisito è mantenere soltanto dati del turno, non salvarli su disco per evitare un reset occasionale.

Per la diagnosi prepara una sequenza: imposta un valore sintetico, osserva il risultato, ricarica, osserva di nuovo. Poi ripeti il passaggio di ciclo di vita che interessa al requisito. Il test dovrebbe distinguere ciò che deve continuare da ciò che deve essere cancellato. Un valore rimasto quando dovrebbe sparire è anch’esso un bug.

Scegli la durata del dato prima di cambiare stato

Se il dato serve soltanto al codice attualmente caricato, una variabile può essere sufficiente. Se deve resistere al reload nella sessione, valuta lo stato previsto dall’API. Se deve vivere su disco, definisci necessità, cancellazione e contenuto minimo prima di usare lo store. In ogni caso prova il passaggio che il requisito promette di supportare.

Due diagnosi ipotetiche in un team italiano

Esempio ipotetico: un’agenzia di Pavia vede il contatore tornare a zero. Il collega modifica il testo della UI e nota il reset. Il gruppo riproduce il caso con pochi eventi e scopre che il valore vive in una variabile di modulo. Non interpreta l’episodio come perdita del repository o problema del modello. Prima decide se il reset è conforme al requisito.

Se il contatore deve coprire la sessione, modifica il meccanismo di stato e aggiunge una prova al reload. Se deve descrivere il codice attualmente caricato, conserva il reset e corregge la descrizione. La stessa osservazione può portare a due scelte corrette: conta ciò che il prodotto ha promesso, non la preferenza implicita del primo autore.

Esempio ipotetico: una PMI di Ancona non vede un mod approvato. La funzione compare sulla macchina del responsabile ma manca su quella gestita di un collega. Il team raccoglie versione, fonte e motivo di rifiuto. Non abbassa i controlli per far apparire il pannello. Verifica se il pacchetto è stato distribuito attraverso il percorso organizzativo previsto.

Il confronto mostra perché installazione e governance devono essere coerenti. Un plugin abilitato da una configurazione gestita può restare nel tier utente se arriva dalla cache di una fonte ordinaria. La guida a Mods per team e sicurezza spiega questo confine, senza promettere che ogni abilitazione equivalga a provenienza gestita.

Quali tentativi peggiorano il debugging?

Il primo è cambiare versione, policy e codice nello stesso tentativo: perdi il confronto. Il secondo è cancellare il sintomo con una reinstallazione senza conservarne il motivo. Il terzo è trattare la sessione che continua come prova che l’handler è riuscito. Il quarto è salvare tutto su disco per evitare i reset. Il quinto è disabilitare un controllo organizzativo per correggere un problema di UI.

Un metodo migliore modifica una sola ipotesi e ripete la sequenza minima. Quando una prova fallisce due volte allo stesso modo, fermati e ricontrolla il livello del problema. Se il modulo non è caricato, una correzione del render non lo aiuterà. Se il dato è giusto ma vecchio, il manifest può essere irrilevante. La gerarchia del sintomo evita patch senza direzione.

Quando smettere di correggere e ridisegnare la prova?

Se due tentativi producono lo stesso sintomo, ricontrolla la domanda iniziale. Potresti stare provando una UI dove serve verificare il caricamento, oppure una variabile quando il requisito riguarda la durata della sessione. Torna al caso minimo e scegli una sola evidenza che distingua due ipotesi. La prossima modifica deve servire a quel confronto, senza moltiplicare impostazioni e copie del plugin.

Come consegnare una diagnosi utile al responsabile?

Prepara una nota con comportamento atteso, comportamento osservato, versione, superficie, fonte del plugin e riproduzione minima. Aggiungi l’estratto di log pertinente e il risultato della verifica effettuata. Distingui causa confermata, ipotesi esclusa e limite ancora aperto. Un report breve con prove vale più di un’intera cronologia di tentativi.

Se una personalizzazione deve diventare stabile nel tuo team, una software house può collegare diagnosi, test e distribuzione al repository. Le guide a Claude Code e ai test Mods aiutano a trasformare il difetto riproducibile in un controllo che prevenga la ricomparsa.