Mods do Claude Code: instale, use e desative com segurança
Mods são plugins com function hooks dentro do processo que podem redesenhar a interface, adicionar comandos e interceptar chamadas de ferramenta. Este guia passa pelo seu primeiro mod, a lista embutida e os interruptores de desligar — com cada fato conferido na documentação oficial.
Resumo
- Mods são plugins do Claude Code que vêm com um módulo de hooks — JavaScript que roda dentro do próprio Claude Code e pode observar, reescrever ou responder eventos.
- Na v2.1.287 ou mais nova, os mods funcionam de fábrica: instale com /plugin install name@marketplace e o mod fica ativo após reiniciar a sessão.
- O mod embutido You Should Know é opt-in: ative uma vez com /plugin enable cc-plugin-you-should-know@builtin.
- Para ficar de fora: desative um mod específico no /plugin, inicie com --safe-mode para uma sessão, ou coloque "disableAllHooks": true para manter todos os mods instalados desligados.
Claude Mods Make Claude Code 10x More Powerful
Canal: Firecrawl4:40
Claude Code v2.1.287 — Claude Mods and Agent Plugins
Canal: Claude Code Changelog2:13
Mods overview — official docs (function hooks)
Docs: code.claude.com/docs
As capturas vêm dos dois vídeos acima; só foram usados trechos limpos de tela e slides tipográficos de changelog — trechos com apresentador ficaram de fora. Os fatos foram conferidos com a documentação oficial dos mods, não com os vídeos.
Os carimbos de tempo apontam de volta para os vídeos de origem, para a visita chegar aos criadores. Claude Code é uma marca da Anthropic; este guia é independente e sem vínculo.
Instalar e usar seu primeiro mod do Claude Code
Entender o que é um mod
- 1
Saber o que um mod muda
O Claude Code 2.1.287 introduz os mods: plugins que mudam comportamento mais profundo do próprio agente. Um mod pode reagir a eventos da sessão, manter estado próprio e desenhar direto na interface — um programinha que estende o seu terminal, não mais uma instrução para o modelo.
Notas da v2.1.287 apresentando os mods como plugins que mudam comportamento mais profundo dentro do Claude Code.Assistir em 0:30 - 2
Posicionar os mods entre as outras camadas de extensão
Skills orientam o comportamento do modelo, servidores MCP expõem ferramentas externas, shell hooks executam comandos em eventos do ciclo de vida. Mods são a quarta camada: código que roda dentro do processo, pode mudar a interface e interceptar eventos antes ou depois de acontecerem. A cola abaixo do walkthrough compara as cinco camadas.
- 3
Conferir sua versão do Claude Code
Mods exigem Claude Code v2.1.287 ou mais novo, onde vêm ativados por padrão. Rode claude --version para conferir; se estiver atrasado, siga nosso tutorial de atualização do Claude Code e volte. Mods individuais podem pedir builds ainda mais novos.
Notas da v2.1.287 cobrem: Claude Mods, o plugin You Should Know, filtragem do agent view e gerenciamento de tarefas em segundo plano.Assistir em 0:09
Instalar um e vê-lo rodar
- 4
Pular o flag de ativação antigo
Walkthroughs antigos mandam definir CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 — aquela era a prévia de acesso antecipado. Desde a 2.1.287 os mods vêm ativos por padrão e a variável é ignorada, então você pode tirá-la das configurações. Não precisa de mais nada para ligar os mods.
- 5
Instalar um mod de um marketplace
Dentro de uma sessão: /plugin install mod-name@marketplace; do seu terminal: claude plugin install mod-name@marketplace e depois /reload-plugins se já tem uma sessão aberta. Antes de instalar código de terceiros, você pode conferir com claude plugin validate ./some-mod.
- 6
Ler o que um mod realmente é
Um mod é um módulo de hooks: uma entrada register(on) que assina funções handler aos eventos do motor. Cada handler recebe a API dos mods, o evento e uma continuação next() — o formato de middleware do Express, em que você observa, reescreve ou responde ao evento e então passa adiante.
O register.tsx de um mod real: um handler on('ui.render') que redesenha o componente AbovePrompt com uma linha extra de texto.Assistir em 2:35 - 7
Rodar a sessão e verificar
Inicie o Claude Code e procure as provas: os comandos de barra do mod aparecem na lista de ajuda, e o /plugin mostra uma linha como "1 mod active" abaixo das abas. Se nada aparecer, releia as instruções do mod — mods com desenho só funcionam no terminal e na aba Code do app desktop.
O comando /hello na lista de ajuda vem de um mod instalado — mods podem registrar comandos próprios de execução imediata sem gastar um turno do Claude.Assistir em 2:32
Os mods embutidos
- 8
Conhecer os mods embutidos
Abra o /plugin e olhe a seção Built-in: cc-plugin-agents-md carrega AGENTS.md, cc-plugin-diff sustenta o painel /diff, cc-plugin-plugin-authoring é a skill de autoria de plugins, cc-plugin-sec-default guarda a política da organização e cc-plugin-telemetry cuida da analítica. O código-fonte deles vive no diretório de mods do repositório do Claude Code.
- 9
Ativar o mod You Should Know
You Should Know é o agente lateral embutido do Claude Code: uma vez ativado, ele vigia sua sessão e aponta coisas que talvez tenham te escapado. Vem desativado por padrão — ligue uma vez com /plugin enable cc-plugin-you-should-know@builtin e ele fica ligado para as próximas sessões.
O cartão oficial you-should-know: um agente lateral que monitora sua sessão, ativado com /plugin enable cc-plugin-you-should-know@builtin.Assistir em 0:48 - 10
Conhecer os três interruptores de desligar
Desative um mod específico na aba Installed do /plugin. Inicie com claude --safe-mode para uma única sessão sem mods. Ou coloque "disableAllHooks": true em ~/.claude/settings.json para manter todos os mods instalados desligados até você reverter. Mods embutidos seguem rodando nos três casos — é de propósito.
Manter o controle
- 11
Respeitar o modelo de segurança
Mods rodam com as suas permissões e sem sandbox: podem ler variáveis de ambiente e segredos, reescrever prompts, pré-aprovar chamadas de ferramenta e gastar sua cota. Só instale mods que você rodaria como código puro na sua máquina, e audite com /plugin o que uma sessão carregou de verdade.
- 12
Saber onde os mods podem desenhar
A UI dos mods — painéis ao lado da transcrição, faixas acima do prompt, abas próprias — renderiza no terminal e na aba Code do app desktop. Não desenha em sessões WSL, no painel de chat do VS Code, em execuções claude -p, no Agent SDK nem em sessões cloud, e um mod pode restilizar a UI do Claude Code, mas nunca o prompt de permissão.
Mods vs plugins vs skills vs MCP vs hooks
O Claude Code agora tem cinco camadas de extensão, e os nomes se embaralham rápido. A versão curta — onde o código roda e o que ele pode tocar:
- 1Skills são pacotes de instruções em markdown que orientam o comportamento do modelo quando invocadas — sem executar código próprio.
- 2Servidores MCP conectam ferramentas e fontes de dados externas pelo Model Context Protocol — fora do processo, expostos como ferramentas.
- 3Shell hooks são comandos dos seus arquivos de configuração que rodam em eventos do ciclo de vida, como antes ou depois de uma chamada de ferramenta.
- 4Plugins empacotam qualquer um desses — comandos, agentes, servidores MCP, hooks — num pacote instalável.
- 5Mods são plugins cujo módulo de hooks roda dentro do processo: funções TypeScript que podem redesenhar a UI, interceptar eventos em pleno voo e guardar estado entre eventos.
Regra de bolso: instruções vão em skills, integrações em MCP, automação em shell hooks, empacotamento em plugins — e quando você precisa mudar como o próprio Claude Code parece ou como um evento se resolve, isso é um mod.