Mod pronto ou mod próprio no Claude Code: quando vale a pena escrever o seu?

Fala aí, beleza? Sabe quando tu instala o fluxo de outra pessoa e passa mais tempo adaptando do que usando? 😛

Pois é, agora tem uma saída nova pra isso

A Anthropic lançou os mods do Claude Code em 1º de outubro de 2026, e até agora não houve recuo

Um mod é um plugin que muda a aparência e o comportamento do Claude Code

Por baixo, são handlers de eventos em JavaScript ou TypeScript que o Claude Code chama quando algo acontece: uma chamada de ferramenta, um prompt enviado, o desenho de uma parte da interface

E o handler pode só observar, pode alterar ou pode assumir o evento por completo

Aí vem a dúvida que importa: instalo um mod que alguém já fez ou escrevo o meu?

Bora destrinchar isso com critério, sem achismo 🙂

O que um mod do Claude Code consegue fazer (e o que isso muda na escolha)

Antes de decidir entre pronto e próprio, vale saber o tamanho do brinquedo

Segundo a documentação e o anúncio oficial, um mod pode:

• Reescrever um prompt antes de ele seguir adiante
• Desenhar interface: um painel ao lado da transcrição ou uma faixa acima do prompt, com abas, botões e campos de texto
• Interceptar uma chamada de ferramenta ou requisição: segurar a chamada pra perguntar algo ao usuário, responder sem rodar a ferramenta ou mandar a requisição pra outro modelo
• Substituir um recurso nativo ou adicionar funcionalidade nova
• Rodar código próprio num /comando sem gastar turno do Claude, mesmo com ele trabalhando

Ou seja, é bem mais que um ajuste de configuração

É código seu rodando dentro do harness

Nem todo problema pede mod:

Aqui mora a pegadinha que muita gente vai cair

A Anthropic tem uma divisão oficial de papéis que ajuda MUITO na decisão:

• CLAUDE.md é o que o Claude sempre sabe: comandos de build, layout do projeto, convenções do time
• Skill é um procedimento sob demanda
• Hook é uma regra que o harness impõe num evento fixo, independente do que o Claude decida

O mod vive nessa terceira categoria, com superpoderes de interface e interceptação

Então se o que te incomoda é o Claude não saber que o teu projeto usa tal padrão de pasta… isso é CLAUDE.md, não mod

Se é um passo a passo que tu chama de vez em quando, é skill

Mod entra quando tu precisa que algo aconteça SEMPRE, no evento certo, ou quando quer mexer na interface e no fluxo das ferramentas

Requisito de versão:

Mods exigem Claude Code v2.1.287 ou posterior

E vêm ligados por padrão, então não tem chave escondida pra ativar

Eles chegam dentro do sistema de plugins que já existia e são instalados com o comando /plugin, tanto no CLI quanto no app desktop do Claude Code

Mod pronto x mod próprio: comparação de esforço, manutenção e risco

Coloquei os critérios lado a lado pra facilitar

Um detalhe sobre o lado do mod pronto

Marketplace no Claude Code não é loja hospedada: é um repositório ou diretório com o arquivo .claude-plugin/marketplace.json, que lista plugins e de onde buscar cada um

O marketplace oficial da Anthropic é adicionado sozinho na primeira sessão interativa no terminal, a não ser que uma política gerenciada bloqueie

Quando um mod da comunidade já resolve

Se a tua dor é a mesma de muita gente, provavelmente alguém já resolveu

A própria Anthropic publicou exemplos que cobrem casos bem comuns

Exemplos no repositório anthropics/claude-code:

• diff: painel de diff
• agents-md: carregamento de agents.md
• sec-default: padrões de segurança
• telemetry: telemetria

Exemplos no claude-code-playground:

• token-weather: uma previsão da janela de contexto, tipo boletim do tempo pros seus tokens haha
• blast-radius: barra comandos arriscados, os rm -rf da vida
• replay-theater: um comando /replay pras edições

E a comunidade já começou a se mexer

No GitHub tem o tópico claude-code-mods, com repos de terceiros como o MarcoCarnevali/claude-code-mods

Pra plugins com curadoria da Anthropic, a referência é o diretório oficial anthropics/claude-plugins-official

Como gerenciar mods prontos pelo /plugin:

Rodando /plugin abre o gerenciador com quatro abas:

• Discover: navega pelos plugins dos marketplaces
• Installed: vê, habilita, desabilita e desinstala o que já tem
• Marketplaces: adiciona ou remove marketplaces
• Errors: mostra erros de carregamento

Pra instalar direto um plugin específico, o formato é este:

/plugin install commit-commands@claude-plugins-official

Dentro de uma sessão, esse comando abre o painel do plugin pra tu revisar e escolher o escopo antes de instalar

E pra gerenciar depois:

/plugin disable
/plugin enable
/plugin uninstall

Tome cuidado!

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

A orientação oficial é instalar só de fontes confiáveis, como qualquer código que tu roda no teu computador

Repo da comunidade pode ser ótimo, mas abre o código e lê antes de instalar, beleza?

Um mod que intercepta chamada de ferramenta tem poder pra fazer coisa boa e coisa ruim na mesma medida

Quando vale a pena escrever o seu próprio mod

Agora o lado de quem já cansou de adaptar fluxo alheio

Se liga nos sinais de que a tua regra é particular demais pra um mod genérico:

• Convenção interna do time que precisa ser imposta, não só lembrada
• Interceptação específica de ferramenta: tu quer segurar uma chamada pra perguntar algo antes, ou responder sem rodar a ferramenta, num caso que só existe no teu projeto
• Painel com informação só sua: dados do teu projeto ao lado da transcrição ou numa faixa acima do prompt
• /comando que dispara uma rotina própria, rodando direto sem esperar turno do Claude

Se tu se viu em dois ou três desses, provavelmente está gastando mais energia contornando o mod dos outros do que gastaria escrevendo o teu

E o caminho é mais curto do que parece

Dá pra escrever o mod à mão ou pedir pro próprio Claude Code escrever, descrevendo o que tu quer numa sessão

Se a IA travar no meio do caminho, vale aquela régua de saber quando parar de insistir com a IA e mexer no código tu mesmo, que aqui é pequeno e bem delimitado 😀

Como montar um mod próprio mínimo no Claude Code

Bora ver na prática?

Pra detalhes do manifesto e da lista de eventos, a fonte é a doc de criação de mods

1. Crie a estrutura de três arquivos

first-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

O plugin.json é o manifesto do plugin, o hooks.json aponta pro código e o register.js é o código em si (chamado de hooks module)

O erro comum deste passo: largar o plugin.json na raiz em vez de dentro de .claude-plugin/

2. Aponte o código com a chave modules no hooks.json

É a chave modules que dá o caminho do código e é ela que transforma um plugin comum em mod

O caminho é relativo ao próprio hooks.json, então se os dois estão na mesma pasta, aponta direto pro register.js

O erro comum deste passo: esquecer a chave modules, ou escrever o caminho relativo à raiz do mod em vez de relativo ao hooks.json

Aí o plugin até existe, mas não é mod

3. Exporte register(on, options) no arquivo de entrada

export function register(on, options) {
  // aqui você registra os handlers dos eventos
  // consulte os tipos gerados pra ver os eventos disponíveis
}

O arquivo pode ter extensão .js, .mjs, .cjs, .jsx, .ts, .mts, .cts ou .tsx

E não precisa de Node.js, bundler nem build: o Claude Code carrega .js e .ts direto

Se tu conhece hooks de outras ferramentas, a ideia é bem semelhante: registrou, o harness chama no momento certo

O erro comum deste passo: não exportar a função com o nome register

4. Entenda $ e next() antes de escrever lógica

Dentro do hook, a API de mods chega como $

E o next() é o coração da coisa:

• Chamou next(): o evento segue adiante
• Não chamou: o evento é interrompido
• Alterou o argumento do evento antes de chamar next(): o evento é reescrito

É assim que um mod observa, altera ou assume

O erro comum deste passo: esquecer o next() num handler que era só pra observar e bloquear o evento sem querer

Tu fica olhando pro Claude Code parado sem entender nada… haha

5. Salve e use os tipos gerados

O mod recarrega sozinho ao fim de cada turno que altera os arquivos dele

Numa sessão interativa, os arquivos são observados, então salvou, recarregou

A cada carga ou recarga, o Claude Code grava arquivos de declaração TypeScript em .claude-plugin/types/, descrevendo os eventos, os métodos da API de mods e os elementos da versão que tu está usando

Isso dá autocomplete e checagem de tipos no editor, e é ali que tu descobre os eventos disponíveis sem chutar

O erro comum deste passo: editar à mão os arquivos de .claude-plugin/types/ (eles são regravados na próxima carga) ou não olhar a aba Errors do /plugin quando o mod não aparece

Veredito: qual caminho escolher

Sem fórmula mágica, mas dá pra resumir em poucas regras:

• É contexto fixo (build, layout, convenções)? Vai de CLAUDE.md, nem precisa de mod
• É um procedimento que tu chama quando precisa? Skill
• A necessidade é genérica (diff, barrar comando perigoso, acompanhar contexto)? Mod pronto, de fonte confiável e com o código lido
• A regra é tua, do teu time ou do teu projeto? Escreve o mod

E tem o caminho do meio, que costuma ser o mais esperto

Pega um exemplo oficial que chega perto do que tu quer e adapta

Tu herda uma estrutura que já funciona e só troca a lógica pela tua regra

Como o mod é teu a partir dali, a manutenção também é, então mantém ele pequeno e focado

Próximo passo

Pra sair do papel hoje:

1. Confere se teu Claude Code está na v2.1.287 ou posterior
2. Roda /plugin e explora a aba Discover
3. Achou algo? Lê o código antes de instalar
4. Não achou nada que sirva? Descreve o mod que tu quer pro Claude Code numa sessão e parte dali

E independente do caminho, revisa SEMPRE o código de qualquer mod de terceiros

Sem sandbox, quem decide o que roda na tua máquina é tu 😉

Até o próximo post!