O que são Mods no Claude Code e o que eles mudam na sua sessão?

O Claude Code agora pode ser reescrito por você, da interface ao comportamento 😀

Fala aí, beleza? A Anthropic soltou os mods e, se liga, isso muda MUITO o quanto dá pra mexer na ferramenta

Eles chegaram no Claude Code v2.1.287, lançado em 1 de outubro de 2026, junto com o post oficial Customize Claude Code with mods in TypeScript no blog da Claude

E funcionam em dois lugares: no CLI do Claude Code e na aba Code do app Claude Desktop

Neste post eu te conto o que são os mods no Claude Code, como funcionam por dentro, o que mudam na sua sessão e onde mora o perigo (porque tem perigo sim haha)

Como um mod funciona por dentro?

Primeiro o porquê, depois o como

Pela documentação oficial, um mod é um plugin que muda a aparência e o comportamento do Claude Code

Ele é feito de event handlers em JavaScript ou TypeScript que o Claude Code chama quando acontece um evento: uma chamada de ferramenta, um prompt enviado ou uma parte da interface sendo desenhada

E o handler pode fazer três coisas com esse evento: observar, alterar ou assumir o controle dele

Que event handler? Se você já mexeu com JavaScript no navegador, a ideia é bem semelhante a escutar um clique: você diz "quando acontecer tal coisa, roda essa função"

Só que aqui a tal coisa acontece dentro da sua sessão do Claude Code 🙂

O hooks module e a função register:

O mod sempre vem dentro de um plugin

O arquivo de entrada dele se chama hooks module, um arquivo JS ou TS cujas funções o Claude Code chama quando os eventos acontecem

Quando o mod carrega, o Claude Code chama a função register exportada por esse arquivo e passa pra ela uma função chamada on

Cada chamada de on registra um handler (que a doc chama de hook) para o evento indicado

Os três argumentos de todo hook:

O Claude Code passa pra todo hook os mesmos três argumentos:

• $: a API de mods
• e: o evento
• next: o próximo handler

Se você conhece middleware de servidor Node, o nome next já deve soar familiar né? 😛

Quais arquivos tem um mod pequeno?

Um mod pequeno tem só três arquivos:

• plugin.json: o manifesto do plugin
• hooks.json: aponta para o arquivo de código
• register.js: o código em si, ou seja, o hooks module

O formato exato está na doc de criação de mods, e mais pra frente tu vai ver que nem precisa escrever isso na mão…

O que um mod muda na sua sessão do Claude Code?

Aqui tá a parte massa

O mod mexe em duas frentes: no que o Claude Code FAZ e no que ele MOSTRA

O que muda no comportamento:

• Reescrever um prompt antes de ele chegar ao modelo
• Bloquear ou repetir uma chamada de ferramenta
• Aprovar ou negar um pedido de permissão
• Ocultar segredos na saída das ferramentas

Ou seja, dá pra ficar no meio do caminho entre você, o modelo e as ferramentas, decidindo o que passa e o que não passa

O que muda na interface:

Os mods podem desenhar uma interface utilizável, tipo um painel ao lado da transcrição ou uma faixa acima do prompt, com abas, botões e campos de texto

E também podem redesenhar a interface do próprio Claude Code, substituindo ou reestilizando partes nativas como:

• A linha de uma chamada de ferramenta
• O spinner
• O diálogo em que o Claude faz perguntas pra você

Isso é algo que nenhuma outra forma de personalização fazia, e daqui a pouco te mostro a comparação 😀

O que chegou na v2.1.288:

Logo na versão seguinte, a v2.1.288 adicionou $.ui.selection() para mods

Ela também corrigiu um bug em que o botão de um mod às vezes executava a ação de outro botão, numa view desenhada antes de o Claude Code reiniciar

Se você pegou a primeira leva e viu botão fazendo coisa que não devia, era isso haha

Exemplos práticos: para que usar mods?

Bora ver onde cada uma dessas capacidades entra no dia a dia?

Ocultar segredos na saída das ferramentas:

Imagina uma ferramenta que cospe na tela uma chave que estava num arquivo de config

Um mod pode esconder esse segredo da saída antes de ele virar parte da conversa

Bloquear chamadas de ferramenta arriscadas:

Sabe os rm -rf da vida? Um mod pode bloquear a chamada de ferramenta antes de ela rodar

E também aprovar ou negar pedidos de permissão seguindo a regra que você definir

Reescrever prompts com o padrão do time:

Como o mod reescreve o prompt antes de chegar ao modelo, dá pra garantir que todo pedido saia com as convenções que o time combinou

Criar um painel próprio na sessão:

Um painel ao lado da transcrição, com abas e botões, pra mostrar o que importa pro seu fluxo sem sair do Claude Code

Prova de que isso é usado de verdade:

A conta ClaudeDevs disse que a própria equipe usou mods para construir recursos como o /diff e o suporte a AGENTS.md

Ou seja, não é brinquedo de fim de semana, é a mesma base que eles usam pra montar recurso oficial

E nas empresas?

Os planos Team e Enterprise carregam primeiro um mod embutido chamado sec-default

Ele foi feito pra impedir ações arriscadas, como passar por cima de negações de permissão

Mods vs hooks de settings: qual a diferença?

Se você já usava hooks no settings.json, deve estar pensando: "mas isso eu já tinha, né?"

Tinha uma parte, se liga:

Resumindo: o hook de settings dispara algo de fora a cada evento e esquece tudo depois

Já o mod vive dentro da sessão, lembra do que aconteceu e ainda conversa com o Claude Code e com a tela

Se você só precisa disparar um comando ou uma requisição quando algo acontece, o hook de settings resolve

Se precisa de estado entre eventos, interface ou chamar o Claude Code de volta, aí é mod

Como instalar ou criar um mod no Claude Code:

Aqui não é next, next e finish, mas quase haha

1. Confirme que você está no Claude Code v2.1.287 ou posterior

Os mods exigem essa versão mínima

O erro comum deste passo: tentar usar mod numa versão antiga e achar que o recurso não existe

2. Instale o mod como qualquer plugin, pelo comando /plugin

Como os mods vêm dentro de plugins, você instala e compartilha do mesmo jeito, pelo /plugin no CLI ou no app desktop

3. Responda ao prompt de confiança do diretório

Numa sessão interativa em um diretório que você ainda não marcou como confiável, nenhum mod carrega até você responder esse prompt

O erro comum deste passo: instalar, abrir a sessão numa pasta nova e concluir que o mod está quebrado, quando na real ele só está esperando a sua confirmação

4. Alternativa: peça pro Claude escrever o mod

Você pode descrever o mod que quer numa sessão interativa do Claude Code e o Claude escreve pra você

Ele usa uma skill embutida chamada plugin-authoring, que diz onde escrever o mod, quais eventos e métodos a sua versão tem e como o mod é carregado

O erro comum deste passo: usar o mod gerado sem ler o código, e já já tu vai entender por que isso é perigoso

Mods são seguros? Riscos e como desligar

Tome cuidado aqui!

A causa do risco:

Os mods rodam com o mesmo acesso à máquina que o próprio Claude Code e não têm sandbox

Eles podem ler e escrever arquivos, iniciar processos e fazer requisições de rede

E tem um detalhe que pega muita gente: o sandboxing do Bash não cobre os mods

Com o sandboxing ativado, ele isola os comandos Bash que o Claude roda, mas um processo iniciado por um mod roda FORA desse isolamento

O sintoma:

A sessão começa a se comportar estranho: prompt saindo diferente do que você digitou, ferramenta sendo bloqueada sem motivo, interface mudada

A solução:

Pra descobrir se o culpado é um mod, inicie a sessão em safe mode:

claude --safe-mode

Isso desliga os mods instalados (e também outras personalizações)

Se o problema sumiu, achou o suspeito 😀

Como o safe mode começa uma sessão nova, se você estava no meio de algo vale saber como retomar a sessão do Claude Code sem perder o trabalho

Pra desligar um mod só, desative ou desinstale o plugin dele na aba Installed do /plugin

Como prevenir:

Instale mods só de autores e marketplaces confiáveis, essa é a recomendação oficial

Em Team e Enterprise, pra desativar os mods instalados, o admin define allowManagedModsOnly e não distribui mods próprios

Na prática: o que um plugin bem feito faz com a sua sessão

Antes de tudo, um aviso honesto: o exemplo aqui é o Context Mode, que é um plugin do ecossistema do Claude Code

Não estou afirmando que ele é um mod, beleza? Uso ele pra mostrar o tipo de controle sobre a sessão que um plugin consegue dar

No vídeo abaixo eu mostro o Context Mode funcionando num projeto real

Como ele funciona, do jeito que eu mostrei:

No vídeo eu mostro um infográfico com a ideia: sem o plugin, tudo que você pede ao Claude vai pro contexto até compactar e esquecer coisas

Com ele, um sandbox filtra o que não importa antes de entrar no contexto

Resumindo o fluxo: a cada prompt, um hook intercepta a chamada, filtra a sujeira e salva o histórico completo num banco local (SQLite), pra reinjetar informação relevante quando o Claude compacta o contexto

O teste que eu rodei:

Instalei o plugin pelo comando de plugin marketplace apontando pro repositório do autor

Depois rodei uma sequência de prompts reais num projeto: análise, correção de vulnerabilidades de segurança e, por fim, uma funcionalidade de estatísticas

Nessa última pedi um endpoint com total de tarefas concluídas, pendentes, porcentagem de conclusão, tarefas por categoria e a categoria com mais pendências

E ajustes no frontend pra mostrar tudo com cards visuais e uma barra de progresso animada

A ideia era gerar trabalho suficiente pra conseguir medir alguma diferença

O resultado:

No fim usei um comando do próprio plugin pra checar o status, e ele mostrou:

• 84 KB de dados processados pelo plugin durante o teste
• 40 KB que foram pra sandbox e nunca entraram no contexto
• Uma economia de tráfego de tokens de 50%, estimada pelo próprio plugin

Se você curte acompanhar esse tipo de número, dá pra ver quanto token a sessão gastou com outra ferramenta também

O que isso tem a ver com mods?

Esse plugin já mostra o quanto dá pra mexer no que entra e no que sai da sua sessão

Os mods levam isso um passo além: handlers rodando dentro do processo, mantendo estado entre eventos e ainda desenhando na interface

Ou seja, esse tipo de controle fica muiiito mais fácil de construir 🙂

Vale começar a usar mods agora?

Na minha visão, os mods são a forma mais profunda de personalizar o Claude Code hoje: mexem no comportamento, na interface e conversam com a sessão por dentro

Porém, sem sandbox, a confiança na origem vem antes de tudo

Mod de autor desconhecido tem o mesmo acesso à sua máquina que o Claude Code, então pensa duas vezes antes de instalar qualquer coisa

O próximo passo que eu sugiro: atualiza pra v2.1.287 ou posterior, abre uma sessão interativa e pede pro Claude um mod simples, tipo ocultar segredos na saída das ferramentas

E lê o código que ele gerar antes de usar, nada de modo 100% vibe coder aqui haha

Bora testar e me conta o que você criou!

Até o próximo post! 😀