Mods do Claude Code: o que são e o que entregamos em cada agente

Em 1º de outubro de 2026, o Claude Code 2.1.287 saiu com uma única linha no changelog: "Added Claude Mods". Quatro dias depois, o AgentsRoom começou a carregar um dos nossos nos agentes Claude que ele executa.

Este artigo explica o que é um mod, o que ele faz que os pontos de extensão anteriores não faziam, como escrever, carregar e testar um, e o que aprendemos ao entregar um mod dentro de cada agente Claude que o AgentsRoom inicia. Os fatos sobre o Claude Code vêm da documentação e do changelog dele, consultados em 9 de novembro de 2026, com o Claude Code 2.1.318 instalado.

A resposta curta. Um mod é um plugin do Claude Code com um hooks module: um arquivo JavaScript ou TypeScript cujas funções o Claude Code chama de dentro do seu próprio processo quando um evento acontece. Uma função pode deixar o evento passar, modificá-lo ou respondê-lo no lugar do Claude Code. É assim que um mod desenha um painel, adiciona um comando ou para um comando shell antes que ele seja executado.

O que é um mod

O Claude Code já tinha plugins: uma pasta com um manifesto em .claude-plugin/plugin.json que agrupa skills, subagentes, hooks de settings e servidores MCP para que sejam instalados como uma única unidade. Um mod é mais uma coisa que um plugin pode conter. Quando o hooks/hooks.json do plugin aponta um arquivo de código na sua chave modules, o Claude Code carrega esse arquivo e chama a função register que ele exporta. O plugin passa então a se chamar mod.

Dentro de register, cada chamada a on(event, hook) associa uma função a um evento: tool.call antes de uma ferramenta ser executada, prompt.submit quando você envia um prompt, session.start, command.run para um comando slash, ui.render quando o Claude Code desenha uma parte da sua tela, e outros. Cada hook recebe três coisas:

• $, a API dos mods: tudo o que um mod pode fazer fora do seu próprio código, como $.ui, $.command, $.fs, $.process ou $.http.
• e, o evento, como dados simples: para uma chamada de ferramenta, o nome da ferramenta e seus argumentos.
• next, que passa o evento para os outros mods e depois para o comportamento do próprio Claude Code, e devolve o resultado.

O que o hook faz com next decide o que acontece. Retorne next(e) e você apenas observou. Chame next com uma cópia modificada de e e você reescreveu o evento. Retorne o seu próprio resultado sem chamar next e você o respondeu: a ferramenta nunca é executada, ou o Claude Code nunca desenha a parte dele.

A documentação também chama essas funções de hooks. Elas não são os hooks que você escreve no settings.json, que o Claude Code agora chama de settings hooks.

Mod, hook de settings, skill ou servidor MCP

Os quatro se sobrepõem, e o mod é o mais pesado deles. Escolha o mais leve que resolva o problema.

Um plugin pode conter os quatro, então um mod pode ser distribuído ao lado da skill e do servidor MCP com os quais ele trabalha.

Os três arquivos de um mod

my-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.ts

plugin.json é o manifesto habitual de um plugin: um nome, uma versão, uma descrição. hooks.json aponta para o código, { "modules": ["./register.ts"] }, um único caminho relativo a esse arquivo. register.ts é o hooks module. O Claude Code carrega .js e .ts diretamente, sem bundler e sem etapa de build, e o único import sem caminho permitido é claude-code, para os tipos e alguns utilitários.

O mod que entregamos: quem alterou este arquivo?

O AgentsRoom executa vários agentes de código no mesmo repositório e mostra, na sua aba Alterações, qual agente alterou qual arquivo, para que você possa revisar e fazer commit do trabalho de cada agente separadamente. Os arquivos escritos com as ferramentas Edit e Write do Claude eram fáceis: o Claude Code os informa por um hook de settings. Os escritos por um comando shell, não. Um sed -i, um heredoc, um codemod ou um rm nunca passam por uma ferramenta de arquivos.

Antes dos mods, a gente adivinhava. O AgentsRoom lia a transcrição da sessão do agente para saber quando cada comando Bash começava e terminava, e depois comparava a data de modificação do arquivo com esses intervalos. Funcionava na maior parte das vezes e falhava de três formas que sabíamos nomear:

• um arquivo apagado não tem data de modificação, então uma exclusão nunca era atribuída;
• um comando somente leitura como grep abria um intervalo durante o qual o agente podia ter escrito qualquer coisa;
• tudo dependia do formato da transcrição, que o Claude Code é livre para mudar.

Um mod elimina o palpite. O nosso mod agentsroom-changes intercepta tool.call para as duas ferramentas shell. Logo antes de o comando ser executado, ele tira um snapshot do repositório (git status mais o tamanho e a data de modificação de cada caminho modificado). Logo depois, tira um segundo. Os caminhos que diferem são o que esse comando alterou, exclusões incluídas, e o mod os envia para o app desktop do AgentsRoom por um endpoint HTTP local. Uma chamada que o próprio Claude Code marca como somente leitura não reivindica nada.

Aqui está o hook, encurtado. O arquivo completo tem 177 linhas, a maioria para o snapshot e os seus limites.

import type { Register } from 'claude-code';

const SHELL_TOOLS = new Set(['Bash', 'PowerShell']);

export const register: Register = (on) => {
  on('tool.call', async ($, e, next) => {
    if (!SHELL_TOOLS.has(e.tool)) return next(e);
    const ready = await prepare($).catch(() => null); // agent id, repo root, snapshot
    if (!ready) return next(e);                        // outside AgentsRoom: do nothing
    const callId = e.tool_use_id;
    post($, ready.agentId, { kind: 'start', callId });
    const ran = await next(e);                         // the command runs here
    const wroteNothing = ran.deny !== undefined || ran.isReadOnly === true;
    await reportEnd($, { ...ready, callId }, wroteNothing)
      .catch(() => post($, ready.agentId, { kind: 'end', callId, paths: [] }));
    return ran;                                        // Claude sees the normal result
  });
};

O app desktop copia o mod para a sua própria pasta e inicia cada agente Claude com claude --plugin-dir <that folder>, somente quando o Claude Code instalado é a 2.1.287 ou mais recente. Nós o lançamos no AgentsRoom 1.201.0, em 5 de outubro de 2026.

O que aprendemos ao lançá-lo

Um mod nunca deve custar ao usuário uma chamada de ferramenta. O nosso hook fica na frente de cada comando shell que o Claude executa. Se ele lançar um erro, ou ficar esperando a rede, o trabalho do Claude para. Cada etapa é protegida, cada envio para o app desktop sai sem esperar resposta, e a única espera que aceitamos são dois snapshots git status, limitados a 15 segundos cada. Um envio perdido custa uma atribuição, nunca o comando.

Não faça nada quando ninguém pediu. O mod lê uma variável de ambiente que o AgentsRoom define para os seus agentes. Quando ela não existe, por exemplo porque alguém copiou a pasta para a própria configuração, cada hook vai direto para next(e).

Uma pasta carregada com --plugin-dir é monitorada. O Claude Code recarrega o mod quando um arquivo dessa pasta muda, e uma recarga executa register de novo. Isso definiu como o instalamos: o app desktop só grava um arquivo do mod quando o conteúdo dele mudou, porque uma regravação cega a cada inicialização de agente recarregaria o mod em todos os consoles do Claude já abertos.

Conte com mudanças na API. Os eventos e os métodos podem mudar de uma versão para outra, e a própria documentação diz isso. Quando um mod é carregado a partir de --plugin-dir, o Claude Code grava as declarações de tipos da versão em execução em .claude-plugin/types/; verificamos os tipos contra elas, não contra uma página web. E se uma versão deixar de carregar o nosso mod, nada quebra: o mod nunca se declara pronto, e o AgentsRoom volta ao antigo método da transcrição.

Escreva o seu

Você tem dois caminhos.

Peça ao Claude. Em uma sessão interativa do Claude Code, descreva o mod que você quer ("mostrar o branch git atual acima do prompt"). O Claude usa uma skill integrada, plugin-authoring, escreve o mod em uma pasta para essa sessão, e o Claude Code pergunta uma única vez se você quer ativar os mods que o Claude escreve. Responda sim e o mod é carregado quando o turno termina, e depois é recarregado após cada turno que o altera.

Escreva você mesmo os três arquivos, e depois:

claude --plugin-dir ./my-mod       # load it for one session, hot reload on save
claude plugin validate ./my-mod    # what Claude Code reads from it, without running it
claude plugin test                 # run the mod's *.test.ts files, no session needed

claude plugin validate imprime uma linha hooks: com os eventos que o seu módulo trata e uma linha calls: com cada método da API dos mods que ele chama. Se faltar um evento que você pretendia tratar, o Claude Code também não vai chamar esse hook. A análise estática tem regras: escreva cada chamada por inteiro ($.ui.toast(...), nunca const ui = $.ui), passe os nomes de eventos como literais de string, e importe apenas os seus próprios arquivos por caminho relativo.

Para compartilhar um mod, trate-o como o plugin que ele é: envie a pasta, ou publique-o em um marketplace (um repositório com um .claude-plugin/marketplace.json) para que as pessoas o instalem com /plugin install <name>@<marketplace>.

Mods que você pode ler hoje

• Integrados ao Claude Code: /plugin, aba Installed, seção Built-in. Entre eles, o painel /diff e o carregador que lê o AGENTS.md como instruções do projeto, cujo código a Anthropic publica na pasta mods do repositório anthropics/claude-code, com os seus testes. Também integrado, e desligado até você ativá-lo: You should know, um agente lateral que aponta o que você ou o Claude podem ter deixado passar.
• Os exemplos da Anthropic, no repositório claude-code-playground: uma previsão da janela de contexto desenhada acima do prompt, uma proteção que segura um comando shell arriscado e mostra o que ele mudaria, e um comando /replay que percorre passo a passo as edições do último turno.
• O nosso, descrito acima: um mod sem nenhuma interface, um único hook tool.call, um bom formato para copiar se o que você precisa são dados e não um painel.

Antes de instalar o mod de outra pessoa

Um mod não fica isolado em um sandbox. Ele é executado com as suas permissões: pode ler e gravar seus arquivos, ler suas variáveis de ambiente e suas configurações (chaves de API incluídas), iniciar programas, fazer requisições de rede, ver cada prompt e cada chamada de ferramenta, e aprovar uma chamada de ferramenta antes que perguntem a você. Se você ativou o sandbox do Claude Code, ele cobre os comandos Bash que o Claude executa, não os processos que um mod inicia.

Então leia antes de instalar. Clone o mod e execute claude plugin validate na pasta: as linhas hooks: e calls: dizem o que ele escuta e o que ele alcança, sem executar nada. Um mod que só desenha uma faixa acima do prompt não tem motivo para chamar $.http ou $.process. Para parar todos os mods que você instalou, inicie com --safe-mode durante uma sessão, ou defina "disableAllHooks": true em ~/.claude/settings.json.

Onde os mods funcionam

Um mod que desenha deve verificar onde está sendo executado e recorrer ao texto onde nada é desenhado.

No AgentsRoom

Você não instala nada: a partir do Claude Code 2.1.287, cada agente Claude inicia com o mod, e a aba Alterações mostra os arquivos que cada um dos seus comandos shell criou, modificou ou apagou, ao lado do agente que fez isso. Com um Claude Code mais antigo, o AgentsRoom continua atribuindo as escritas shell a partir da transcrição, como antes.

A mesma ideia funciona em outros CLIs quando é possível: o oh-my-pi recebe uma extensão com o mesmo contrato, e os outros CLIs continuam atribuindo as escritas shell do jeito de antes. Se você quiser ir mais longe no que o Claude Code expõe a cada etapa, o nosso guia de hooks do Claude Code cobre os hooks de settings ao lado dos quais um mod se posiciona.

Perguntas frequentes

O que é um mod no Claude Code?

Um mod é um plugin do Claude Code que contém um hooks module: um arquivo JavaScript ou TypeScript cujas funções o Claude Code chama de dentro do seu próprio processo quando algo acontece, como uma chamada de ferramenta, um prompt enviado ou uma parte da tela a ser desenhada. Cada função pode deixar o evento passar, modificá-lo ou tratá-lo ela mesma. É isso que permite a um mod desenhar um painel, adicionar um comando ou segurar um comando shell arriscado.

Qual versão do Claude Code eu preciso para usar mods?

Claude Code 2.1.287 ou mais recente no terminal, lançada em 1º de outubro de 2026, cujo changelog diz "Added Claude Mods". A aba Code do app Claude Desktop os aceita a partir da 2.1.286. Na extensão do VS Code os hooks são executados, e o que um mod desenha exige a extensão 2.1.299 ou mais recente. Execute claude --version para conferir.

Qual é a diferença entre um mod e um hook do Claude Code?

Um hook no settings.json executa um comando shell, uma requisição HTTP ou um prompt quando um evento dispara, fora do Claude Code. Os hooks de um mod são funções executadas dentro do Claude Code. Eles fazem o que um hook de settings não consegue: desenhar na interface, adicionar um comando slash executado sem um turno do Claude, reescrever uma chamada de ferramenta ou respondê-la sem executar a ferramenta, e compartilhar estado entre hooks.

É seguro instalar mods do Claude Code?

Um mod não fica isolado em um sandbox. Ele é executado com as suas permissões, pode ler seus arquivos e suas variáveis de ambiente, iniciar programas, fazer requisições de rede e aprovar uma chamada de ferramenta. Instale mods apenas de autores em quem você confia, e execute antes claude plugin validate na pasta: ele lista os eventos que o mod escuta e as chamadas que faz, sem executá-lo.

Onde encontro exemplos de mods do Claude Code?

A Anthropic publica o código de alguns mods integrados, como o painel /diff e o carregador do AGENTS.md, na pasta mods do repositório anthropics/claude-code, e mods de exemplo no repositório anthropics/claude-code-playground. O do AgentsRoom descrito neste artigo é um quarto tipo de exemplo: um mod sem interface, só com um hook tool.call.

Posso desativar os mods?

Sim. Desative um mod na aba Installed do /plugin, inicie uma única sessão com --safe-mode, ou defina disableAllHooks como true em ~/.claude/settings.json para parar todos os mods que você instalou, junto com os seus hooks de settings. --safe-mode e disableAllHooks deixam os mods integrados funcionando: esses são desligados um por um no /plugin.