Mods do Claude Code: veredito com fontes, medições e checklist de segunda

Resumo

• Fique com três dos dez mods: collision-guard, model-router e auto-handoff. Cada um mostrou sobrecusto medido próximo de zero em uma tarefa de leitura headless, e cada um resolve um problema que você sabe nomear.
• Apague next-steps. Ele faz fork da sessão após cada resposta elegível e custou +250 tokens de saída e +2850 ms por turno no nosso teste, inclusive em superfícies que nunca desenham suas sugestões.
• Apague cache-keeper (+1589 ms, pings pagos ao modelo), recording-mode (ele mascara a exibição, não o histórico armazenado) e session-bookmarks (um marcador que pode chamar o modelo, rodar processos e gravar arquivos).
• Apague goal-meter, repo-heatmap e flight-recorder, a menos que você queira o visual. Custam quase nada e não mostraram benefício medido.
• Todo mod de guarda falha aberto por padrão. Sem um handler .catch, uma guarda que lança erro é ignorada e o comando roda.
• Mods não rodam em sandbox. Leia a saída de claude plugin validate antes de instalar um.

O que as medições dizem

Hype e escala. O tweet de lançamento tinha 4,138,918 views, 20,021 likes e 13,440 salvamentos quando o capturamos em 2026-10-03 s11. O catálogo da comunidade lista 1018 mods em 873 repositórios candidatos, escaneados em 2026-10-03 no Claude Code 2.1.288 s9.

Um mod é uma função que se pendura em um evento. Ela pode rodar antes, depois, no lugar do evento, ou envolvê-lo s1. Mods exigem Claude Code v2.1.287 ou superior e vêm ativados por padrão s2.

Segurança primeiro. Nas palavras da Anthropic: "Mods run with the same access to your machine as Claude Code itself. They aren't sandboxed" s1. Um processo iniciado por um mod roda fora do sandbox mesmo com o sandbox ligado s2. Com Read(.env) negado, um mod ainda pode ler esse arquivo com $.fs.read ou iniciar um programa que leia s6. No escaneamento do catálogo, 409 mods rodam processos do host, 167 gravam arquivos, 150 acessam a rede e 28 falham na validação nesta versão s9.

Alcance versus promessa. Na nossa auditoria estática, session-bookmarks chama $.model.complete, $.process.run e $.fs.write, o maior alcance do conjunto para uma função de marcador. next-steps tinha a menor pegada: sem fs, sem process, sem env. claude plugin validate imprime as linhas calls: e env reads: usadas nesta auditoria s6.

O mod principal tem um custo por turno. next-steps faz fork da sessão com $.model.fork em turn.complete, e o README diz que o fork "costs about one short reply" s10. As sugestões só aparecem no terminal; as outras superfícies não mostram nada s10. O fork não tem opção para desativar. No nosso teste headless ele somou +250 tokens de saída e +2850 ms, com o fork caindo no uso da sessão sem que nada fosse exibido s10.

Limites documentados. O tempo de execução de um hook é limitado a 10 segundos por evento, leituras e gravações de $.fs a 4 MiB por arquivo e $.store a 4 MiB de JSON no total s3.

Guardas falham abertas. A doc diz que um hook sem handler .catch que lança erro, estoura o tempo ou retorna o formato errado é ignorado, e o próximo handler roda no lugar s7. Reproduzimos: uma guarda de Bash que lança erro, sem .catch, deixou touch ./marker-failopen.txt criar o arquivo. A mesma guarda com um .catch retornando {deny} não criou arquivo nenhum. Um relato de campo encontrou uma guarda ativada e rodando mas sem fazer nada, enquanto plugin list ainda mostrava "enabled" s8.

Um bug aberto no 2.1.288: um deny retornado depois de await next(e) não para a ferramenta, e o arquivo foi gravado 3 de 3 vezes enquanto o modelo era informado de que a gravação falhou s5.

Mods versus hooks de settings. Um hook de settings inicia um processo por chamada. Medimos a inicialização em 2.2 ms para um binário true, 8.3 ms para bash -c 'exit 0', 26.1 ms para python3 -c 'pass' e 43.1 ms para node -e ''. Em 5,993 chamadas de ferramenta por semana, o hook node custa 258 s. Um mod em processo não paga nada disso. A doc recomenda um hook de settings quando você já tem um script que bloqueia, permite ou registra um evento s2. Um relato de migração foi de 27 hooks de shell para 5 mods s8.

Mascaramento é só visual. recording-mode reescreve o que ui.render desenha. ~/.claude/history.jsonl guarda o prompt como digitado, e um testador encontrou sua string canário 7 vezes em entradas queue-operation do transcript s5.

Onde mods não rodam. O modo headless claude -p e o Agent SDK rodam hooks mas não desenham nada; uma sessão Desktop WSL não roda nenhum dos dois s2.

Confiança no catálogo. Um testador publicou um mod cujo botão iniciava um programa com $.process.run e gravava um arquivo na sua pasta pessoal. Ele instalou como qualquer outro mod, sem aviso algum s5. Foi uma prova de conceito autopublicada, não um ataque visto na prática.

Medições

Corpus: os últimos 7 dias de uma configuração real, 85 sessões, 4 projetos, 882 prompts de usuário, 11,010 turnos do assistente, 5,993 chamadas de ferramenta. Benchmark rodado no Claude Code 2.1.288 (macOS).

Protocolo para repetir:

1. Instale um mod por vez e confirme que ele passa em claude plugin validate.
2. Rode a mesma tarefa somente leitura em headless com claude -p no haiku, 3 repetições por configuração, e pegue a mediana da duração e dos tokens de saída.
3. Cite só as diferenças de duração e de tokens de saída. O custo em USD varia com a ordem do cache entre configurações, ignore.
4. Para o custo de inicialização, cronometre 30 inicializações do corpo de cada hook, pegue a mediana e multiplique pelo seu número semanal de chamadas de ferramenta.

Faça isto na segunda

• Rode claude plugin validate em cada mod instalado e leia as linhas calls: e env reads:.
• Desative qualquer mod cujo alcance (process, gravação fs, chamada ao modelo) seja maior que sua função.
• Desative next-steps se você trabalha principalmente em headless, no painel do VS Code ou no SDK, onde as sugestões nunca aparecem.
• Adicione um handler .catch que retorne { deny: ... } a cada mod de guarda em que você confia.
• Prove que cada guarda falha fechada: faça-a lançar erro, rode um comando que cria um arquivo marcador e verifique que o arquivo não aparece.
• Não confie em um mod de mascaramento para manter segredos fora de ~/.claude/history.jsonl ou do transcript. Confira os dois no disco.
• Troque hooks de shell por chamada que rodam node ou python por um mod em processo, ou por um binário compilado, se o custo de inicialização pesar nas suas chamadas semanais de ferramenta.
• Aprenda os interruptores: desativar um mod em /plugin, --safe-mode para uma sessão, "disableAllHooks": true em ~/.claude/settings.json para tudo.

Para ir além

• Construa o seu: um passo a passo prático de um mod de cerca de 80 linhas, com as armadilhas que importam (o estado no nível do módulo é resetado no hot reload, então guarde os dados em $.state) s4.
• Decida entre mod, hook, skill ou settings a partir do seu próprio histórico: um praticante sugere minerar seus logs de sessão primeiro para achar problemas recorrentes s12.
• Leia a lista completa de eventos e limites antes de escrever uma guarda s3.
• Gestão em nível de organização está fora do escopo aqui. O único ponto para um desenvolvedor solo: sec-default carrega quando a máquina tem settings gerenciados ou você está logado com um plano Team ou Enterprise, e não adiciona outras restrições s6.
• A origem do design, incluindo um bug de isolamento de worktree corrigido no 2.1.288 e os internos do runtime, está na thread aberta s5.
• Mods de exemplo da Anthropic (token-weather, blast-radius, replay-theater) são listados como compartilhados sem suporte s2.

Fontes

• Customize Claude Code with mods, Anthropic blog. Por que ler: a definição oficial e o aviso de que não há sandbox, nas palavras da Anthropic.
• Mods overview, docs. Por que ler: a comparação mods versus hooks, a matriz de superfícies e os interruptores.
• Mods reference, docs. Por que ler: a lista completa de eventos e os limites documentados.
• Getting started with Claude Code mods, claude.dev (Addy Osmani). Por que ler: o melhor passo a passo prático, com armadilhas que nenhuma outra fonte cobre.
• Mods issue #91870, GitHub. Por que ler: relatos de campo sobre isolamento, falha fechada e vazamentos de histórico.
• Manage mods for your organization, docs. Por que ler: a auditoria validate e os limites de cada controle de segurança.
• React to events with a mod, docs. Por que ler: a ordem da cadeia de middleware e a falha aberta por padrão.
• The Guard I Installed Was Enabled, Running, and Doing Nothing, blog. Por que ler: o único relato de migração, de 27 hooks de shell para 5 mods.
• awesome-claude-code-mods, GitHub. Por que ler: o tamanho do ecossistema e um método de auditoria pronto.
• next-steps plugin source, GitHub. Por que ler: a mecânica real do mod principal, incluindo o fork a cada turno.
• ClaudeDevs release tweet, X. Por que ler: o anúncio de lançamento e seu alcance.
• Avid's session-log mining workflow, X. Por que ler: um método para decidir o que construir ou instalar antes de instalar qualquer coisa.

FAQ

Mods rodam em sandbox?

Não. A Anthropic diz que mods rodam com o mesmo acesso à sua máquina que o próprio Claude Code s1. Programas iniciados por um mod também rodam fora do sandbox s2.

O que acontece se minha guarda travar?

Sem handler .catch, ela é ignorada e o comando roda s7. Adicione um .catch que retorne { deny: ... } para que ela falhe fechada.

Um mod gasta tokens?

Só se chamar o modelo. Dos dez que rodamos, next-steps e cache-keeper mostraram custo mensurável; os outros não mostraram sobrecusto robusto no nosso teste.

Como desligo os mods rapidamente?

Desative um em /plugin, inicie uma sessão com --safe-mode, ou defina "disableAllHooks": true em ~/.claude/settings.json s2. Nenhum desses desliga os mods embutidos.

Posso conferir o que um mod faz antes de instalar?

Sim. claude plugin validate lista os hooks, as chamadas de API e as variáveis de ambiente que ele lê s6.