Descubra por que um mod não faz nada
Quando um mod não faz nada, duas verificações encontram o motivo: o que Claude Code lê dos arquivos do mod e a linha que ele escreve quando ignora algo. Para a primeira, em seu shell executeclaude plugin validate com o diretório do mod, como em claude plugin validate ./first-mod. Isso detecta um evento digitado incorretamente, um manifesto ruim e um módulo que Claude Code não consegue ler, sem iniciar uma sessão.
Quando um módulo não carrega, um hook é ignorado ou outro mod recusa o seu, Claude Code escreve uma linha que nomeia seu mod. Onde você lê essa linha depende da sessão:
- Uma sessão que recarrega dinamicamente um diretório de plugin: uma linha fraca na transcrição. Essa é uma sessão interativa que você iniciou com
--plugin-dir, ou uma onde você habilitou o recarregamento dinâmico para mods que Claude escreveu. - Qualquer outra sessão interativa, como uma que executa um mod que você instalou de um marketplace: o log de depuração apenas. Para obter um, inicie a sessão com
claude --debug. - Uma execução
claude -pcom--plugin-dir: stderr, no formato de saída de texto padrão. Uma recusa por outro mod vai apenas para o log de depuração.
Verifique se os mods podem carregar
Para verificar se sua configuração permite que os mods carreguem, sem instalar um, executeclaude plugin test em seu shell, a partir de um diretório que não contenha um mod. Você não precisa de uma sessão. A mensagem que ele imprime informa o estado:
Uma organização também pode definir
allowManagedModsOnly para permitir apenas seus próprios mods, o que este comando não relata. Nesse caso, um mod que você instala não carrega, e uma mensagem diz por quê.
O mod não carrega
Nada que o mod adiciona aparece: nenhum comando, nenhum desenho e nenhuma mudança de comportamento.Sua versão é mais antiga que 2.1.287
claude --version imprime uma versão mais antiga que 2.1.287. Sua versão é anterior aos mods estarem ativados por padrão.
Atualize Claude Code.
A linha mods active não nomeia o mod
Nada que o mod adiciona aparece, e a linha mods active em /plugin não o nomeia. O módulo hooks não carregou. Quando Claude Code o recusou, o log de depuração tem uma linha que começa com hooks module, o nome do mod e not loaded:, como em hooks module first-mod@inline not loaded: disableAllHooks in managed settings para um mod carregado com --plugin-dir.
Leia o motivo após os dois pontos. A seção mensagens de recusa lista cada uma. Se o log não tiver tal linha, trabalhe através das outras entradas neste grupo.
Uma execução claude -p imprime hooks module not loaded
A linha começa com o nome do mod e vai para stderr. O módulo hooks foi recusado. Uma execução não interativa não tem transcrição, então a mensagem vai para stderr.
Leia o motivo após os dois pontos. A seção mensagens de recusa lista cada uma.
Mensagens de recusa
Cada uma delas seguehooks module, o nome do mod e not loaded: no log de depuração.
Mensagens do guarda integrado
Em uma máquina com configurações gerenciadas, ou para um usuário conectado com um plano Team ou Enterprise, o guarda integrado pode recusar um mod ou uma de suas respostas. Cada mensagem nomeia a opção que o administrador de sua organização define para alterar a regra.validate passa e não lista nenhuma linha hooks
hooks/hooks.json não tem uma chave modules, ou a chave está digitada incorretamente.
Adicione "modules": ["./register.js"].
hooks module did not load
A linha começa com o nome do mod, depois hooks module did not load: e um motivo, que fornece o arquivo e a linha quando o problema está em seu código. Claude Code não conseguiu carregar o módulo, por exemplo porque seu código de nível superior lançou.
Corrija o erro que o motivo nomeia.
options do not fit plugin.json userConfig
A linha começa com o nome do mod, depois hooks module did not load: options do not fit plugin.json userConfig: e um motivo. Uma opção não se encaixa em seu campo userConfig, como um número acima do max do campo, ou um campo obrigatório não tem valor.
Defina ou altere o valor. O final da linha nomeia sua entrada pluginConfigs em settings.json.
Nenhum mod carrega em um diretório que você abriu pela primeira vez
Você não respondeu ao prompt de confiança para o diretório. Inicie uma sessão interativa nesse diretório comclaude e aceite o prompt de confiança que ele abre.
Nenhum plugin instalado carrega
Você iniciou Claude Code com--safe-mode.
Inicie sem a flag.
Um hook é ignorado ou um mod é descarregado
O mod carregou e então Claude Code ignorou um de seus hooks ou o descarregou.hook skipped
A linha nomeia o mod e o evento, depois diz hook skipped: e um motivo, como em first-mod: tool.call hook skipped: threw Error: boom. Um hook lançou, executou além de seu limite de tempo de 10 segundos, ou retornou um resultado de forma incorreta. A linha aparece uma vez para cada evento e tipo de falha até o mod recarregar.
Corrija o erro. O log de depuração tem uma linha para cada ocorrência.
it crashed the hooks worker
A linha começa com o nome do mod, como em first-mod was unloaded: it crashed the hooks worker. Os mods instalados compartilham um thread de worker. O worker parou de responder ou travou, e Claude Code rastreou isso para este mod e o descarregou. Um hook que bloqueia a thread, como um loop que nunca aguarda, é uma causa.
Corrija o hook.
mods that run in the hooks worker are off for this session
A linha lê hooks: mods that run in the hooks worker are off for this session: it crashed 3 times. O worker parou três vezes e Claude Code não conseguiu rastrear as paradas para um mod, então descarregou cada mod que não é integrado, incluindo mods que sua organização instala. Esta linha chega à transcrição em cada sessão interativa.
Execute /reload-plugins para carregá-los novamente.
Uma chamada de ferramenta é recusada
O mod carregou e seus hooks executam, e uma chamada de ferramenta que ele tocou é recusada.a hook changed this call's input after the model wrote it
Em modo automático, uma chamada de ferramenta recusada fornece este motivo. Um hook alterou a entrada da chamada de ferramenta após o classificador do lado do servidor revisá-la, então essa revisão não cobre o que seria executado. O hook pode ser um tool.call ou turn.step hook do mod, ou um hook de configurações PreToolUse. A mensagem não diz qual.
A mensagem diz a Claude para emitir a chamada novamente conforme registrado. Se isso também for recusado, o hook altera a entrada toda vez, então desative o mod ou hook, ou saia do modo automático e aprove a chamada você mesmo.
Uma mensagem sobre as regras de negação em suas configurações
tried to lift a deny rule in your settings e the deny rules in your settings could not be checked for this call, so it is refused ambas vêm do guarda integrado.
Procure-as em Mensagens do guarda integrado.
Um desenho não aparece ou responde
O mod carregou e seu painel, banda ou controles não se comportam como você espera.Um painel ou banda está vazio ou mostra o conteúdo usual de Claude Code
A árvore que seu hook retornou não validou. Com--plugin-dir, a transcrição diz ui.render (Pane) refused: com o motivo, como em first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own. O log de depuração tem a hook returned a tree that does not validate com o mesmo motivo.
Leia o motivo nessa linha. As causas comuns são uma prop que o elemento não aceita e um elemento que o aplicativo não tem.
$.ui.open executa e nenhum painel aparece
A chamada não veio de algo que o usuário fez, e o terminal é mais estreito que 144 colunas.
Abra o painel a partir de um comando ou botão, ou verifique o resultado isPlaced da chamada. Veja Abrir um painel no momento certo.
Hotkeys não fazem nada
Seu painel não tem foco de teclado. Pressione Ctrl+X depois Tab, ou clique no painel. Abra-o comfocus: true a partir de um comando.
Um desenho funciona no terminal e não no aplicativo Desktop
O site ou elemento não está disponível lá. Verifique as render sites e tabelas de elementos.Uma edição ou um valor é perdido
O mod executa e uma mudança que você fez ou um valor que ele manteve não está lá.Suas edições não entram em vigor
Você está editando um plugin que instalou. Claude Code executa a cópia em cache para a versão instalada. Desenvolva com--plugin-dir apontado para sua cópia de trabalho, como em claude --plugin-dir ./first-mod, que recarrega quando você salva.
Um valor é redefinido quando o módulo recarrega
Variáveis de nível de módulo são reinicializadas em cada recarregamento. Mantenha o valor em$.state ou $.store.
Um valor é redefinido após /clear, /resume ou /branch
Um valor é redefinido, ou um valor salvo é substituído por seu padrão. Cada um desses comandos redefine $.state para seus padrões, e session.start não dispara novamente.
Carregue o valor salvo novamente em um hook classic.SessionStart.
Leia o log de depuração
O log de depuração tem uma linha para cada módulo que Claude Code carrega ou recusa, cada hook que falha e cada resultado que recusa, então é onde procurar quando a transcrição não mostra nada. Para escrever um, em seu shell inicie Claude Code com--debug, ou com --debug-file <path> para escolher onde ele vai:
--plugin-dir aparece sob seu nome seguido por @inline:
$.ui.log com um segundo argumento, como em $.ui.log('message', { to: 'debug' }). Sem o segundo argumento, $.ui.log adiciona uma linha fraca à transcrição.
Enquanto você edita um mod carregado com --plugin-dir, a transcrição mostra uma linha para cada recarregamento que nomeia o mod e lista seus hooks. Se um salvamento quebrar o módulo, a linha diz reload failed, the previous version stays loaded: com o motivo, e a última versão de trabalho continua executando.
Próximas etapas
- Teste um mod: detecte problemas antes que eles cheguem a uma sessão
- Solucionar problemas de plugins: problemas com instalação e carregamento de um plugin que não são específicos de mods