Aula 18Mods: a novidade que muda a cara do Claude Code

Objetivos

Ao final desta aula você vai saber:

• O que é um mod, numa frase
• O que um mod pode fazer no seu computador depois de carregado
• Por que quem não lê código não instala mod de terceiros
• Ver os mods que já vêm com o Claude Code, sem instalar nada
• Desligar um mod, abrir uma conversa sem mods e desligar todos os seus

Na Aula 15, você conheceu as ações automáticas, que rodam um comando seu num momento certo. Um mod vai mais longe: ele muda o próprio Claude Code. É uma novidade, e vem com um cuidado novo.

A aula é curta e só de olhar. Ela usa a pasta da sua página e mais nada: você não instala nenhum mod, e o curso não precisa de nenhum. Ela vale para o Claude Code 2.1.287 ou mais novo. Para conferir, rode claude --version no terminal, antes de abrir o Claude Code.

O que é um mod

Um mod é um código que muda o Claude Code por dentro (a aparência e o que ele faz sozinho) e roda com as suas permissões.

Alguns exemplos do que um mod faz:

• abre um painel ao lado da conversa, como um gráfico de quanto do contexto já foi usado;
• põe uma faixa acima da caixa de mensagem;
• mostra um contador enquanto o Claude trabalha;
• cria um comando de barra novo, que responde na hora;
• segura um comando arriscado e mostra o que ele mudaria antes de deixar seguir.

Alguns recursos do próprio Claude Code já são mods. O painel do /diff, que você usou na Aula 09, é um deles. Esses vêm de fábrica, e você não precisa fazer nada com eles.

A diferença para a ação automática da Aula 15: ela roda um comando seu, por fora, num momento certo; o mod roda dentro do Claude Code e pode mudar o que você vê e o que ele faz.

O que um mod pode fazer no seu computador

A documentação do Claude Code é direta: um mod é código que roda com as suas permissões, dentro do Claude Code, e só deve ser instalado de autores em que você confia. Depois de carregado, um mod pode:

• agir no seu computador como você: ler e mudar arquivos em qualquer pasta sua, inclusive o .env, abrir programas e usar a internet;
• ler os seus segredos: as chaves e senhas guardadas nas configurações do computador e do Claude Code;
• ver a sua conversa: cada pedido que você manda e cada passo do Claude;
• mudar a sua conversa: reescrever um pedido ou um passo, mandar um pedido como se fosse você ou mandar uma mensagem para outra conversa sua;
• agir sem perguntar: aprovar um passo antes de o pedido de licença chegar a você;
• gastar o seu uso: chamar um modelo no seu plano.

E ele não roda isolado: nada separa o mod do resto do seu computador.

E as suas regras deny e ask? Nos planos pessoais, como o Pro e o Max, um mod pode aprovar um comando que elas barrariam, sem perguntar a você. Elas valem para o Claude; um mod pode passar por cima delas.

Quem não lê código não instala mod de terceiros

Por isso, a regra desta aula é direta: se você não lê código, não instale mod de terceiros. Um mod de outra pessoa pode fazer tudo o que está na lista de cima, e só lendo o código dá para saber o que ele faz de verdade. O curso não precisa de nenhum, e os de fábrica já vêm prontos.

• O mesmo vale para um mod que o próprio Claude escreva para você: ele também roda com as suas permissões, e pedir um é coisa de quem lê código. Isso fica em Para ir além.
• Um mod também pode vir dentro da pasta de outra pessoa, na pasta .claude dela. Antes de confiar numa pasta que não é sua, peça ao Claude, na sua pasta de sempre, para listar e explicar em português simples o que tem dentro da .claude dela, sem rodar nada.

🛡️ Antes de aprovar algo que roda código no seu computador (uma ação automática, um mod, um plugin, um conector que roda no computador): instale só o que vem de quem você confia, peça ao Claude para explicar em português simples o que aquilo faz e desligue o que não usa.

O exercício: só olhar

Abra o Claude Code na pasta da sua página, no Manual, e digite /plugin. É a tela dos plugins e dos mods: um mod é um tipo de plugin, e os plugins ficam para a Aula 21. Ela abre na aba Discover (descobrir), o catálogo de instalar. Aqui, não instale nada.

1. Aperte Tab até chegar na aba Installed (instalados).
2. Procure o grupo Built-in (de fábrica). São os mods que vêm com o Claude Code, com nomes que começam com cc-plugin-, como o cc-plugin-diff, o do painel do /diff. Eles não se desinstalam, e quase todos podem ser desligados ali.
3. Fora do Built-in, não deve haver nenhum mod: você não instalou nenhum. Se aparecer um que você não conhece, feche a tela e peça ao Claude para explicar o que ele é, em português simples, antes de qualquer outra coisa.
4. Aperte Esc para fechar, sem mudar nada.

Onde desligar

• Um mod: na mesma lista, a aba Installed do /plugin. Escolha o mod com as setas e aperte Espaço (a barra de espaço) para desligar, ou para ligar de novo.
• Uma conversa inteira sem mods: saia do Claude Code com /exit e abra de novo com claude --safe-mode. Essa conversa começa sem as suas personalizações: sem o CLAUDE.md, as skills, os plugins, as ações automáticas, os conectores e os mods que você instalou. As regras deny e ask continuam valendo, e os mods de fábrica também continuam. Na próxima vez que você abrir com claude, tudo volta.
• Todos os mods que você instalou, em todas as conversas: peça ao Claude: "desligue todos os mods e as ações automáticas nas minhas configurações pessoais". O nome dessa configuração fica em Para ir além. Os de fábrica continuam, e cada um se desliga na lista do /plugin.

Para ir além (opcional): criar, instalar e conferir um mod

🔧 Para ir além (para quem já programa; pode pular): esta parte mostra o que um mod consegue fazer que os outros recursos não conseguem, como pedir um ao Claude ou instalar um pronto, como ele funciona por dentro, como conferir o que ele faz antes de instalar e os outros jeitos de desligar. Se você nunca programou, pule direto para o Na prática.

ℹ️ Versão: mods vêm ligados por padrão a partir do Claude Code v2.1.287 no terminal e v2.1.286 no app desktop. Confira com claude --version (terminal) ou /status numa sessão local da aba Code (desktop).

O que é um mod, para quem programa

Um mod é um plugin que muda a aparência e o comportamento do Claude Code. Ele é feito de funções em JavaScript ou TypeScript que respondem a eventos: o Claude Code chama uma dessas funções quando algo acontece (uma chamada de ferramenta, um prompt enviado, uma parte da interface sendo desenhada) e a função pode observar o evento, mudar o evento ou assumir o evento.

Exemplo de uso: um painel que mostra um gráfico de quanto do seu contexto está ocupado depois de cada pedido.

Mods × hooks da Aula 15

Na Aula 15 você conheceu os hooks configurados no settings.json, que rodam um comando de shell. Os mods também rodam em eventos, mas são funções que rodam dentro do próprio Claude Code. Na documentação, "hook" dentro de um mod é a função do mod, e o tipo da Aula 15 é chamado de settings hook.

O que um mod consegue fazer

Settings hooks, skills, status line e servidores MCP trabalham de fora do Claude Code: rodam um script ou dão texto e ferramentas ao Claude. Um mod roda por dentro, então ele consegue:

• Desenhar uma interface que você usa: um painel ao lado da transcrição ou uma faixa acima do prompt, com abas, botões e campos de texto.
• Redesenhar a interface do próprio Claude Code: substituir ou reestilizar partes como a linha de uma chamada de ferramenta, o spinner ou a caixa de perguntas.
• Entrar no meio de uma chamada de ferramenta ou de um pedido: segurar uma ação enquanto pergunta algo a você, responder sem rodar a ferramenta, ou mandar um pedido para outro modelo.
• Rodar seu código num comando: um /comando que executa sua função na hora, sem gastar um turno do Claude, até enquanto ele está trabalhando.
• Compartilhar dados entre hooks: um hook conta as chamadas de ferramenta e outro mostra a contagem ao lado do spinner.

Qual usar: mod, settings hook, skill ou MCP?

Um plugin pode ter tudo isso junto: um mod, uma skill e um servidor MCP no mesmo pacote.

Como conseguir um mod

1. Use os que já vêm com o Claude Code

Alguns recursos do próprio Claude Code são mods. Para ver os da sua sessão, rode /plugin e vá na aba Installed: eles aparecem em Built-in. Um built-in não se atualiza nem se desinstala, e a linha mods active do /plugin não conta os built-in. Os nomes, como o /plugin mostra:

O --safe-mode, o --bare e o disableAllHooks não param os built-in: cada um tem o próprio interruptor, no /plugin. O código de alguns é público, na pasta mods do repositório do Claude Code.

2. Peça para o Claude criar

O jeito mais fácil: descreva o que você quer numa sessão interativa do Claude Code, e o Claude escreve o mod. Ele usa uma skill que já vem com o Claude Code, a plugin-authoring, que você também pode chamar com /plugin-authoring.

Crie um mod que mostre, ao lado do spinner, quantas chamadas de
ferramenta você já fez neste turno.

Crie um mod com o comando /tempo que abre um painel mostrando há quanto
tempo esta sessão está aberta.

O que acontece depois do pedido:

1. O Claude grava o mod numa pasta da sessão: ~/.claude/dev-mods/<id-da-sessão>/<nome-do-mod>/. Como ~/.claude é um caminho protegido, nos modos manual e accept edits ele pede para criar cada arquivo. Aprove um por um, lendo o que cada um faz.
2. Ao salvar o primeiro arquivo, o Claude Code pergunta se pode recarregar os mods desta sessão. Responda Enable for this session: o mod carrega quando o turno termina e recarrega a cada turno que o muda. (Not now deixa os arquivos lá e só carrega na próxima vez que a sessão abrir.) Depois do Enable for this session, o mod roda com as suas permissões: leia o código antes.
3. Rode /plugin, aperte Tab até a aba Installed e confira se o mod aparece. Dá para desligá-lo ali.

Esse mod só vale para a sessão que o criou, e o Claude Code apaga a pasta da sessão depois de um tempo (o prazo do cleanupPeriodDays). Para guardar, copie a pasta do mod para um lugar seu, como ~/mods/contador, e carregue com claude --plugin-dir ~/mods/contador.

Um mod escrito pelo Claude só carrega depois da sua aprovação, numa pasta em que você confiou e com os mods permitidos. Ele não carrega quando ninguém pode aprovar (num claude -p ou no modo dontAsk), numa pasta em que você não aceitou a pergunta de confiança, nem com os mods desligados (--safe-mode, --bare, disableAllHooks ou as configurações gerenciadas da sua empresa).

3. Instale um pronto

Mods se instalam como plugins, a partir de um marketplace: nome do plugin, @, nome do marketplace.

/plugin install token-chart@sua-empresa

Ou no terminal:

claude plugin install token-chart@sua-empresa

Se instalar pelo terminal com uma sessão aberta, rode /reload-plugins nessa sessão para carregar.

Mods de exemplo da Anthropic (no repositório claude-code-playground, sem suporte oficial):

• token-weather: desenha uma "previsão do tempo" da sua janela de contexto acima do prompt
• blast-radius: segura um comando arriscado (como rm -rf ou um force push), mostra o que ele mudaria e oferece botões para seguir ou cancelar
• replay-theater: adiciona um comando /replay que mostra passo a passo as edições que o Claude fez no último turno

Um mod de exemplo também roda com as suas permissões: liste o que ele faz antes de carregar (veja a seção de segurança, abaixo). Para testar um por uma sessão só, clone o repositório e use claude --plugin-dir <pasta-do-mod>. Para manter, adicione a pasta claude-code/mods do clone como marketplace e instale o mod de claude-code-playground-mods. O marketplace aponta para o seu clone: se você mover ou apagar a pasta, o mod para de carregar.

Como um mod funciona por dentro

Um mod pequeno tem três arquivos:

primeiro-mod/
├── .claude-plugin/
│   └── plugin.json      ← o manifesto do plugin
└── hooks/
    ├── hooks.json       ← aponta para o seu código
    └── register.js      ← o seu código

Este é um register.js completo. Ele conta as chamadas de ferramenta do Claude e mostra a contagem ao lado do spinner, como em Thinking · tool calls: 3…:

// A contagem, compartilhada pelos dois hooks abaixo
let calls = 0

// O Claude Code chama esta função uma vez quando o mod carrega
export function register(on) {
  // Roda toda vez que o Claude vai usar uma ferramenta
  on('tool.call', async ($, e, next) => {
    calls += 1
    // Pede para o Claude Code redesenhar a interface, para a contagem aparecer
    $.ui.invalidate('ui.render')
    // Deixa a ferramenta rodar normalmente
    return next(e)
  })

  // Roda toda vez que o Claude Code desenha o spinner
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    // Mantém o spinner original, com a contagem depois da palavra
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
  })
}

Repare nas três coisas que um hook pode fazer com um evento:

Para fazer qualquer coisa fora do próprio código (desenhar, criar um comando, chamar um modelo, ler um arquivo, abrir um processo, acessar a rede), o hook usa a API de mods (o objeto $). É por isso que dá para listar o que um mod faz antes de instalar.

Segurança: confira o mod antes de instalar

⚠️ Um mod é código que roda com as suas permissões. Ele não roda em sandbox: mesmo com o sandbox ligado, que isola os comandos Bash do Claude, um processo aberto por um mod roda fora dele.

Os detalhes da lista do começo da aula, para quem programa:

• Os segredos que um mod lê são as variáveis de ambiente e os arquivos de configuração, incluindo uma chave de API guardada em qualquer um deles.
• Um mod que aprova uma ação passa por cima das suas regras quando a sessão não tem configurações gerenciadas nem um /login de plano Team ou Enterprise: ele pode aprovar uma ação que uma regra ask pararia, que um settings hook PreToolUse seu bloqueou ou que uma regra deny recusa. Uma sessão com chave de API ou com CLAUDE_CODE_OAUTH_TOKEN não conta como esse /login, mesmo que ele esteja guardado.
• Com configurações gerenciadas ou com o /login de Team ou Enterprise, por padrão a deny continua recusando, a ask continua perguntando e o bloqueio do PreToolUse continua valendo.
• No modo auto, a ação aprovada por um mod nem passa pelo classificador. No modo de planejar, um mod não aprova nada que não seja só leitura, como uma edição ou um comando que escreve.
• Uma ferramenta que exige você, como a pergunta que o Claude faz com o AskUserQuestion, continua perguntando mesmo com a aprovação de um mod (desde a v2.1.292).

Um mod consegue reestilizar muita coisa, mas não consegue mudar o pedido de permissão que você vê.

Antes de instalar, baixe os arquivos e liste o que o mod faz sem rodá-lo:

claude plugin validate ./algum-mod

As linhas hooks: e calls: da saída mostram os eventos que ele escuta e o que ele pede para o Claude Code fazer. O Claude Code se recusa a carregar um mod que use a API de mods de um jeito que esse comando não consegue ler. Na linha calls:, procure estes:

Na linha hooks:, tool.call e prompt.submit querem dizer que o mod vê, e pode mudar, cada chamada de ferramenta e cada prompt; tool.check quer dizer que ele pode aprovar ou recusar uma chamada antes do pedido de permissão. Instale mods só de autores e marketplaces em que você confia.

Ligar, desligar e conferir

• Ver quais mods a sessão carregou: rode /plugin no terminal. Uma linha discreta embaixo das abas mostra, por exemplo, 1 mod active · primeiro-mod. Os built-in não entram nessa linha.
• Desligar um mod: desative ou desinstale o plugin na aba Installed do /plugin (Espaço liga e desliga; Enter abre os detalhes, com Uninstall). No app desktop, o caminho é + → Plugins → Manage plugins.
• Desligar os mods instalados por uma sessão: inicie com claude --safe-mode (desliga também suas outras personalizações).
• Desligar sempre os mods que você instalou: "disableAllHooks": true em ~/.claude/settings.json (seus settings hooks e sua status line também param). O que a sua empresa gerencia continua rodando. O disableAllHooks para o mod e deixa o resto do plugin no lugar: as skills, os comandos, os agentes e os servidores MCP dele continuam carregando.
• Desligar um built-in: --safe-mode e disableAllHooks não alcançam os built-in. Desative o que quiser na aba Installed do /plugin (só o cc-plugin-sec-default, que protege o que a sua empresa gerencia, não desliga).

Onde os mods funcionam

Para testar

1. Rode claude --version e confira se você está na v2.1.287 ou mais nova.
2. Rode /plugin, abra Installed e encontre os mods Built-in.
3. Peça ao Claude: "Crie um mod que mostre ao lado do spinner quantas chamadas de ferramenta você fez." Aprove os arquivos e responda Enable for this session: o mod carrega quando o turno acabar. Depois, faça um pedido que use algumas ferramentas, como "liste os arquivos daqui e leia o README", e veja a contagem subir ao lado do spinner enquanto o Claude trabalha. Leia o register.js que ele gerou e compare com o exemplo desta aula.
4. Num terminal, rode claude plugin validate na pasta do mod (dentro de ~/.claude/dev-mods/) e veja as linhas hooks: e calls:.
5. (Opcional) Clone o claude-code-playground, rode claude plugin validate no token-weather e teste com --plugin-dir.

Documentação oficial: Mods overview (em inglês).

Na prática

Use a pasta da sua página (a confeitaria, ou a da sua ideia).

1. No terminal, rode claude --version e confira se a versão é a 2.1.287 ou mais nova.
2. Entre na pasta e abra o Claude Code: cd Documents/confeitaria, com o nome da sua pasta, e depois claude. Aperte Shift + Tab uma vez e confira se aparece manual mode on.
3. Digite /plugin, aperte Tab até a aba Installed e encontre o grupo Built-in. Confira: fora dele, nenhum mod. Aperte Esc para fechar, sem mudar nada.
4. Peça: "me explique, em português simples, o que um mod pode fazer no meu computador e como eu desligaria todos os que eu instalasse. Só explique, sem mudar nada".
5. (Opcional) Veja o --safe-mode funcionando. Saia com /exit, abra com claude --safe-mode e pergunte: "sem abrir nenhum arquivo, me diga: você recebeu alguma regra da casa no começo desta conversa?". Sem o CLAUDE.md, a resposta é não. Saia com /exit e abra de novo com claude: as regras voltam.

Resumo

• Um mod é um código que muda o Claude Code por dentro (a aparência e o que ele faz sozinho) e roda com as suas permissões.
• Depois de carregado, ele pode agir no seu computador como você, ler os seus segredos, ver e mudar a sua conversa, agir sem perguntar e gastar o seu uso. Ele não roda isolado.
• Nos planos pessoais, um mod pode aprovar um comando que as suas regras deny e ask barrariam.
• Se você não lê código, não instale mod de terceiros. O curso não precisa de nenhum.
• Para ver: /plugin, aba Installed, com os de fábrica em Built-in. Para desligar: um mod, ali mesmo; uma conversa inteira, com claude --safe-mode; todos os seus, pedindo ao Claude.

No próximo módulo, você junta tudo no projeto final e publica a sua página.