O que são mods do Claude Code?

O que são mods do Claude Code? São plugins que rodam o seu próprio JavaScript ou TypeScript dentro do Claude Code, de modo que podem mudar a aparência e o comportamento dele: desenhar uma linha acima do prompt, colocar números na linha de status, recusar um comando de shell perigoso ou adicionar um comando de barra. Os mods chegaram no Claude Code 2.1.287 e vêm ativados por padrão.

Este guia explica do que um mod é feito, o que ele pode e o que não pode tocar, como os mods se diferenciam dos hooks de configuração, dos servidores MCP e das skills, e como avaliar se é seguro instalar um. No final, há um mod funcional que você monta em dois minutos.

O que é um mod do Claude Code?#

Um mod é um plugin comum do Claude Code com um arquivo a mais: um módulo de hooks. O módulo exporta uma função register(on, options). Quando o Claude Code carrega o plugin, ele chama register, e o mod usa on(...) para se inscrever em eventos como "uma ferramenta está prestes a rodar", "um turno terminou" ou "o spinner está sendo desenhado".

Cada handler recebe três argumentos:

• $, a API de mods. Todo efeito que um mod produz passa por ela: $.ui.status, $.ui.toast, $.process.run, $.fs.read, $.command.register e assim por diante.
• e, o evento, por exemplo o comando Bash que está prestes a rodar.
• next, que repassa o evento para o comportamento padrão do próprio Claude Code.

Um handler pode observar (chamar next(e) e olhar o resultado), reescrever (chamar next com um evento alterado) ou responder (devolver o próprio resultado sem nunca chamar next, que é como uma proteção nega uma chamada de ferramenta).

O que transforma um plugin em mod é uma única chave. Se hooks/hooks.json contém modules, o plugin é um mod:

{
  "modules": ["./register.js"]
}

Os mods rodam no processo do Claude Code com as suas permissões de usuário. Eles não ficam em sandbox. A contrapartida útil é que todo efeito precisa passar por $, então o Claude Code consegue ler o código-fonte de um mod e listar exatamente quais eventos ele trata e quais chamadas de API faz antes de você executá-lo.

O que um mod pode mudar?#

A lista de eventos é longa, mas a maioria dos mods usa poucas áreas:

Os mods também podem abrir painéis, registrar ferramentas para o Claude chamar, executar subagentes, ler e gravar arquivos, fazer requisições HTTP e guardar dados em um pequeno armazenamento de chave-valor. Cada uma dessas ações é uma chamada a $ que aparece na validação.

A interface dos mods é desenhada no terminal (incluindo o plugin para JetBrains) e na aba Code do app desktop. No painel de chat da extensão do VS Code, no claude -p e no Agent SDK, os hooks continuam rodando, mas nada é desenhado. Por isso, uma proteção continua te protegendo em execuções sem interface, enquanto um mod de linha de status simplesmente não tem onde mostrar o texto.

Mods vs hooks vs servidores MCP vs skills#

Esses quatro pontos de extensão só se parecem no nome:

• Hooks de configuração rodam um comando de shell em pontos fixos (antes de uma ferramenta, depois de uma ferramenta, ao parar). São processos separados que conversam com o Claude Code por JSON via stdin e stdout. Não conseguem desenhar interface nem manter estado ativo.
• Mods rodam dentro do processo com uma API tipada. Fazem tudo o que um hook faz e ainda desenham em pontos de renderização, registram comandos e ferramentas e reagem a eventos que os hooks nunca veem, como o desenho do spinner ou o início de uma compactação.
• Servidores MCP dão ao Claude novas ferramentas e fontes de dados por meio de um protocolo. É o Claude que decide quando chamá-los. Eles não mudam a interface do Claude Code nem interceptam as ferramentas nativas dele.
• Skills são instruções e arquivos que o Claude carrega quando uma tarefa combina com elas. Mudam o que o Claude sabe, não o que o Claude Code faz.

Uma regra prática: se você quer que o Claude saiba ou consiga fazer algo novo, use uma skill ou um servidor MCP. Se você quer que o próprio Claude Code tenha outra aparência ou outro comportamento, escreva um mod.

Os mods do Claude Code são seguros?#

Um mod pode fazer tudo o que você faz em um terminal, então trate a instalação de um mod como a de qualquer ferramenta de desenvolvimento. Três hábitos mantêm o risco baixo:

1. Leia a saída da validação. claude plugin validate <dir> mostra uma linha hooks: e uma linha calls: para o módulo. Um mod de linha de status que lista $.http.fetch ou $.fs.write merece um olhar mais atento.
2. Confira os selos de permissão. Toda página de mod no ClaudeMods transforma essas chamadas em rótulos simples, como "Executa comandos" ou "Intercepta chamadas de ferramentas", com uma frase explicando por que o mod precisa de cada uma.
3. Conheça os interruptores. /plugin disable <name> desliga um mod. claude --safe-mode inicia uma sessão com todos os mods desativados. "disableAllHooks": true nas configurações os mantém desligados.

As organizações podem ir além. Administradores podem permitir apenas mods gerenciados, bloquear o carregamento manual com --plugin-dir e colocar um mod de proteção aprovado à frente de tudo o que os usuários instalam. Os detalhes estão na documentação de administração de mods.

Qual versão do Claude Code eu preciso?#

Rode claude --version. O terminal precisa da 2.1.287 ou posterior. O app desktop traz a própria cópia do Claude Code, e os mods funcionam nele a partir da 2.1.286. Todo mod deste site informa a versão com que foi testado pela última vez; no momento em que este texto foi escrito, é a 2.1.291.

Monte um mod pequeno para ver um funcionando#

Três arquivos bastam. Crie esta estrutura:

hello-status/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

.claude-plugin/plugin.json:

{
  "name": "hello-status",
  "version": "0.1.0",
  "description": "Writes a fixed message to the Claude Code status line",
  "author": { "name": "Your Name" }
}

hooks/hooks.json contém a chave modules mostrada antes, apontando para ./register.js. Depois, hooks/register.js:

export function register(on) {
  on('session.start', async ($, e, next) => {
    const started = await next(e)
    $.ui.status('hello from my first mod')
    return started
  })
}

Valide antes de executar:

claude plugin validate ./hello-status

No Claude Code 2.1.291, isto é exibido:

  ❯ ./register.js hooks: session.start
  ❯ ./register.js calls: $.ui.status

✔ Validation passed

Agora inicie uma sessão com o mod carregado só nesta execução:

claude --plugin-dir ./hello-status

A linha de status mostra a sua mensagem. Edite o register.js e salve; o Claude Code recarrega o módulo sem reiniciar. O mod é carregado como hello-status@inline e desaparece quando você sai. O tutorial de mods cobre testes e publicação.

Onde encontrar mods#

Os mods são distribuídos por marketplaces de plugins, que são repositórios Git ou URLs com um marketplace.json. O ClaudeMods mantém um, e todo mod do diretório tem uma página com uma gravação de demonstração, o comando de instalação, as opções, o código que faz o trabalho e as permissões que usa. Cada um é validado, testado e gravado em uma build real do Claude Code antes de a página entrar no ar.

Pronto para adicionar um? Como instalar mods do Claude Code cobre todos os métodos de instalação, além de atualização e remoção.