Preciso saber JavaScript ou TypeScript para escrever um Mod no Claude Code?

Fala aí, beleza? O Claude Code ganhou mods, e a primeira pergunta que aparece é: preciso ser fera em JavaScript pra mexer nisso?

Resposta curta: o mod é código JavaScript ou TypeScript, sim, mas isso não quer dizer que você precisa dominar a linguagem antes de começar 🙂

Os mods foram liberados em 1 de outubro de 2026 junto com o Claude Code 2.1.287, e já vêm ativados por padrão

Aí bate a dúvida de quem vive em Python, Go, PHP e por aí vai: dá pra escrever um mod no Claude Code sem ser dev JS? Existe saída pra outra stack? Ou é melhor só instalar um pronto e seguir a vida?

Bora destrinchar isso

Por que o mod do Claude Code é escrito em JavaScript ou TypeScript

Primeiro, o que é um mod?

É um plugin que muda como o Claude Code se parece e se comporta

Ele é feito de event handlers, e aqui vale parar um segundo: que handler?

É uma função que o Claude Code chama quando um evento acontece, tipo uma chamada de ferramenta, um prompt enviado ou uma parte da interface sendo desenhada

E esse handler pode observar, alterar ou assumir o evento

Se você já usou addEventListener no navegador, a ideia é bem semelhante: tu registra uma função e ela é chamada quando o evento rola 😀

Agora o PORQUÊ da linguagem fixa

Os handlers de um mod são funções que rodam DENTRO do processo do Claude Code

É isso que deixa o mod desenhar interface e compartilhar estado, coisa que um script rodando fora do processo não faz

Por isso a linguagem é JS ou TS, e o módulo de hooks aceita estas extensões:

• .js, .mjs e .cjs
• .jsx
• .ts, .mts e .cts
• .tsx

Quanto de JavaScript você realmente precisa saber para escrever um mod

Menos do que parece, se liga

O código do mod (o tal módulo de hooks) faz basicamente três coisas:

• exporta uma função register
• dentro dela, usa a função on que o Claude Code entrega, chamando on(evento, handler) pra cada evento que quer tratar
• escreve os handlers, que recebem três argumentos: a API de mods, o evento e uma função next

O Claude Code chama a register uma vez, quando o mod carrega, e cada on registra um hook pro evento indicado

Ou seja: se tu sabe escrever uma função, passar um callback e mexer num objeto, já tem a base

Como funciona a cadeia com next?

Essa é a parte que mais confunde no começo, então vamos por partes

• chamar next com o evento: a cadeia continua normal
• chamar next com uma cópia alterada do evento: todo o resto da cadeia vê a sua alteração
• retornar um resultado SEM chamar next: a cadeia acaba ali

Tome cuidado com o terceiro caso!

Esquecer de chamar next não é detalhe, é literalmente assumir o evento e cortar o que vinha depois

O que NÃO é exigido

Aqui tem uma notícia boa pra quem não é do ecossistema JS

Não precisa de Node.js, não precisa de bundler e não tem etapa de build

O Claude Code carrega os arquivos .js e .ts direto, sem aquele ritual de configurar ferramenta antes de escrever a primeira linha haha

O único requisito real é a versão: Claude Code v2.1.287 ou mais recente

O que muda para quem programa em Python, Go ou outra stack

Se JS/TS não é a sua praia, tu tem duas saídas honestas

Saída 1: hooks de shell na sua linguagem

O hook de comando funciona de outro jeito: recebe um JSON pelo stdin e devolve uma decisão em JSON pelo stdout

Como é só um comando de shell, aceita qualquer linguagem que rode como comando, então seu script em Python ou seu binário em Go servem

Mas tem o preço

É um processo por chamada e sem memória compartilhada, e como roda fora do Claude Code, não desenha interface

Saída 2: encarar o JS/TS mínimo com ajuda dos tipos

Toda vez que carrega ou recarrega um mod, o Claude Code grava arquivos de declaração TypeScript (.d.ts) em .claude-plugin/types/, dentro do diretório do mod

Esses arquivos descrevem os eventos, os métodos da API de mods e os elementos

Na prática, o editor passa a autocompletar e checar os tipos dos seus hooks, então tu não fica chutando nome de evento nem de método

Pra quem vem de linguagem tipada, isso ajuda MUITO a se sentir em casa

O que só o mod faz

Vale deixar claro: desenhar interface e compartilhar estado entre chamadas são coisas do mod

Se o seu caso precisa disso, o hook de shell não resolve, e aí o caminho é JS/TS mesmo

Mod, hook de shell ou mod pronto: comparação lado a lado

Quando vale escrever o próprio mod e quando vale usar um pronto

Quando faz sentido escrever o seu

Quando tu precisa mexer na interface ou reagir a eventos do Claude Code por dentro

Alguns dos eventos disponíveis:

• tool.call
• prompt.submit
• turn.start e turn.complete
• session.start
• command.run
• ui.render

Pra ter noção do alcance: segundo a cobertura do lançamento feita pelo SourceTrail, a Anthropic transformou três recursos nativos do Claude Code em mods, o painel de diff, o loader de agents.md e a telemetria

Se dá pra fazer isso, dá pra fazer muiiita coisa 😀

Quando um hook de shell resolve

Quando tu só quer bloquear ou validar algo e já tem o script pronto em outra linguagem

Não precisa de interface, não precisa guardar estado, então reescrever em JS seria esforço à toa

Quando instalar um mod pronto

Quando a necessidade já foi resolvida por terceiros ou pela sua organização

Mods são instalados como plugins a partir de um marketplace, no formato nome@marketplace, e o exemplo da documentação é este, rodado dentro de uma sessão do Claude Code:

/plugin install token-chart@your-org

Como criar um mod mesmo sem dominar TypeScript

Agora a parte prática, num caminho enxuto e verificável

1. Peça o mod ao Claude numa sessão normal. Descreva o que tu quer, e o Claude escreve o mod usando uma skill de autoria de plugins que já vem com o Claude Code. Funciona parecido com quando tu monta uma skill de design responsivo: quanto mais claro o comportamento esperado, melhor o resultado. O erro comum deste passo: descrever o objetivo vago e esquecer as exceções. Se o seu caso tem várias regras e casos de borda, vale ver como descrever regra de negócio com exceções antes de pedir

2. Confira a estrutura mínima de três arquivos. O manifesto, o hooks.json e o módulo de hooks:

meu-mod/
  .claude-plugin/
    plugin.json
  hooks/
    hooks.json
    register.js

O hooks.json aponta pro código pela chave "modules", por exemplo "modules": ["./register.js"]. O erro comum deste passo: achar que o caminho é relativo à raiz do mod. Ele é relativo ao hooks.json, por isso no exemplo acima o register.js fica dentro de hooks/

3. Teste localmente com --plugin-dir. Essa flag carrega um diretório de plugin por uma sessão e recarrega o módulo de hooks quando tu salva:

claude --plugin-dir ./meu-mod

Dá pra repetir a flag pra carregar vários diretórios ao mesmo tempo. O erro comum deste passo: esquecer que o carregamento vale só pra aquela sessão, então o mod não aparece nas próximas se tu não passar a flag de novo

4. Valide antes de confiar. O comando claude plugin validate <diretório> lê o manifesto e o módulo de hooks e mostra os erros, os eventos tratados e as chamadas à API de mods que o mod faz. No nosso exemplo, apontando pra pasta meu-mod com o --strict ligado, fica assim:

claude plugin validate ./meu-mod --strict

O --strict trata avisos como erros e o --json gera um relatório legível por máquina. O erro comum deste passo: pular a leitura do relatório. Pra quem não domina TS, a lista de eventos e de chamadas à API é o jeito mais rápido de conferir se o código que o Claude escreveu faz só o que tu pediu

5. Rode os testes automatizados. O claude plugin test executa todo arquivo terminado em .test.ts ou .test.tsx do diretório, sem sessão, sem login e sem rede:

claude plugin test ./meu-mod

Se tu não informar o diretório, ele usa o diretório atual. O erro comum deste passo: nomear o teste fora desse padrão e achar que ele rodou, quando na verdade foi ignorado

6. Recarregue sem reiniciar. Se tu instalou ou atualizou o mod pelo shell com a sessão aberta, rode dentro da sessão:

/reload-plugins

Ele recarrega plugins, skills, agents, hooks, servidores MCP e LSP de plugins sem reiniciar nada

Veredito: escrever o próprio mod ou usar um pronto?

Sem experiência em JS/TS, o caminho realista é um destes dois

Pedir o mod ao Claude e revisar com validate e test, ou instalar um mod pronto de fonte confiável

Mas se liga no ponto mais importante do post todo: mods NÃO rodam em sandbox

Um mod é código que roda com as suas permissões, lê e grava seus arquivos, inicia processos e faz requisições de rede

Então a pergunta que mais importa nem é sobre linguagem, é sobre confiança: tu leu o código ou confia no autor?

A orientação oficial é instalar mods só de autores e marketplaces em que você confia, e eu não pularia essa parte nem por preguiça 😛

Em empresa, o admin ainda tem controle pelas managed settings

• allowManagedModsOnly (em pluginConfigs, na chave cc-plugin-sec-default@builtin) bloqueia os mods trazidos pelos usuários e mantém só os da organização
• allowManagedHooksOnly também existe pra restringir hooks
• disableAllHooks desliga os mods de todos os plugins e todos os hooks de settings

Próximo passo para começar com mods no Claude Code

Recapitulando:

• o mod é JS ou TS porque roda dentro do processo do Claude Code, e é isso que dá interface e estado compartilhado
• o nível exigido é baixo: register, on(evento, handler) e a cadeia com next, sem Node.js, bundler ou build
• quem é de outra stack pode usar hook de shell na própria linguagem, abrindo mão de interface e estado

O primeiro passo é confirmar que tu está no Claude Code v2.1.287 ou mais recente, no CLI ou no desktop, que são onde os mods estão disponíveis

Depois escolhe teu caminho: pedir um mod ao Claude, adaptar um hook de shell na sua linguagem ou instalar um pronto

E se o mod ficar massa e tu quiser compartilhar, um repositório no GitHub com um arquivo de marketplace já vira um marketplace de onde qualquer pessoa instala, com atualização por um push normal

Bora testar? =)

Até o próximo post!