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

🖥️ Versão Desktop. Nesta versão do curso, você usa o Claude Code no app Claude Desktop, na aba Code. Quase tudo é feito por janelas e botões. Quando uma aula pedir para digitar um comando, ela mostra exatamente o que digitar. Nesta aula, você não digita nenhum comando: o exercício é feito com o botão + e com pedidos em português. A parte opcional do fim usa o /status, para conferir a versão, e o terminal integrado do app, para baixar um mod de exemplo.

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 o que está instalado no app, sem instalar nada
• Desligar um mod 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 app com o Claude Code 2.1.286 ou mais novo, que vem dentro dele. Atualize o app antes: no Mac, Claude → Check for Updates; no Windows, Help → Check for Updates.

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, como o que faz o Claude ler um arquivo AGENTS.md, quando a pasta tem um, como instrução do projeto. 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 abrir no app uma pasta que não é sua, peça ao Claude, numa sessão 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

Na aba Code, abra uma sessão na pasta da sua página, no Manual. Os mods ficam junto com os plugins (um mod é um tipo de plugin, e os plugins ficam para a Aula 21):

1. Clique no +, ao lado da caixa de mensagem.
2. Se o menu mostrar Plugins, escolha Plugins e depois Manage plugins (gerenciar plugins). É ali que você liga, desliga ou remove cada plugin instalado. Olhe a lista e feche, sem mudar nada.
3. Se o menu mostrar Add plugins (adicionar plugins) no lugar de Plugins, esse é o catálogo de instalar: feche sem escolher nada.
4. Nos dois casos, confirme com um pedido: "liste os plugins e os mods que eu instalei, em português simples, sem mudar nada". A resposta esperada: nenhum. Se aparecer um que você não conhece, peça ao Claude para explicar o que ele é antes de qualquer outra coisa.

Onde desligar

• Um mod: em + → Plugins → Manage plugins, desligue ou remova o plugin dele.
• 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.
• Uma conversa inteira sem mods: a versão do terminal tem um jeito para isso, a opção --safe-mode, que fica em Para ir além.

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: no app desktop, os mods vêm ligados por padrão a partir da v2.1.286 do Claude Code que vem dentro do app. Confira digitando /status numa sessão Local da aba Code e lendo a linha Claude Code. Se for mais velha, atualize o app (Claude → Check for Updates no macOS, Help → Check for Updates no Windows) e abra uma sessão nova. Para pedir um mod ao Claude (item 2, abaixo), a skill que ele usa exige a v2.1.287 ou mais nova.

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, e já vêm ligados, sem você fazer nada. Um built-in não se atualiza nem se desinstala. A lista deles, com a opção de desligar cada um, fica no /plugin, da versão do terminal (aba Installed, grupo Built-in). Os nomes, como o /plugin mostra:

O disableAllHooks não para os built-in. 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 do app, e o Claude escreve o mod. Ele usa uma skill que já vem com o Claude Code, a 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 o app pede sua aprovação 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. Use o que você pediu: no primeiro exemplo, a contagem aparece ao lado do spinner. Se o mod não fizer o que você queria, diga ao Claude o que mudar; ele recarrega no fim de cada turno que o altera.

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, peça ao Claude para copiar a pasta do mod para dentro de ~/.claude/skills/ (por exemplo, ~/.claude/skills/contador/). O Claude Code carrega como plugin, em toda sessão, qualquer pasta ali que tenha um .claude-plugin/plugin.json, sem instalar nada. Por isso mesmo, copie para lá só o que você leu. Abra uma sessão nova (ou digite /reload-plugins) para carregar. A versão do terminal também carrega um mod guardado com a opção --plugin-dir.

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, nem com os mods desligados (disableAllHooks ou as configurações gerenciadas da sua empresa).

3. Instale um pronto

Mods se instalam como plugins, a partir de um marketplace. No app, numa sessão Local (ou SSH):

1. Clique no botão +, ao lado da caixa de mensagem, e escolha Add plugins. Se o menu mostrar Plugins no lugar, escolha Plugins e depois Browse plugins. O navegador de plugins abre com os plugins dos seus marketplaces.
2. Escolha o plugin, por exemplo token-chart.
3. Escolha o escopo: a sua conta de usuário, este projeto ou só local.

Os comandos /plugin install e claude plugin install são da versão do terminal. Os marketplaces ficam para a Aula 21, no módulo bônus.

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

Para testar um, clone o repositório no terminal integrado do app (Ctrl+`), ou peça ao Claude para clonar, leia o código do mod (veja a seção de segurança, abaixo) e copie a pasta dele, por exemplo claude-code/mods/token-weather, para ~/.claude/skills/, como no item 2. Abra uma sessão nova para carregar. (A versão do terminal testa um mod com a opção --plugin-dir.)

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.
• 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 Plan, 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 veja o que o mod faz sem rodá-lo. A versão do terminal lista isso com o comando claude plugin validate. No app, leia o código do mod, no arquivo que o hooks/hooks.json indica (no exemplo, o register.js): cada on('…') é um evento que o mod escuta, e cada chamada a $.… é algo que ele pede para o Claude Code fazer. No exemplo acima, são on('tool.call', …), on('ui.render', …) e $.ui.invalidate. Você também pode pedir ao Claude: "liste os eventos que este mod escuta e as chamadas que ele faz ao objeto $". Ler o código não executa o mod. Se o código for confuso demais para entender, não instale.

No código, procure estas chamadas:

E, entre os eventos, 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 o que está instalado: clique em + e, se o menu mostrar Plugins, em Plugins e Manage plugins. A linha que conta os mods carregados, como 1 mod active · primeiro-mod, aparece no /plugin, da versão do terminal.
• Desligar um mod: em Manage plugins, desative ou desinstale o plugin.
• 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. A versão do terminal também desliga os mods de uma sessão só, com --safe-mode.
• Desligar um built-in: disableAllHooks não alcança os built-in. Eles se desligam no /plugin, da versão do terminal (só o cc-plugin-sec-default, que protege o que a sua empresa gerencia, não desliga).

Onde os mods funcionam

Atenção: plugins que você instala pelo app não chegam às sessões Cloud do app, e o navegador de plugins não aparece nelas.

Para testar

1. Numa sessão Local, digite /status e confira a linha Claude Code: 2.1.286 ou mais nova para os mods; 2.1.287 ou mais nova para pedir um mod ao Claude.
2. Clique em + e veja o caminho dos plugins: Manage plugins, se o menu mostrar Plugins, ou Add plugins, que abre o catálogo. Não instale nada.
3. Peça ao Claude: "Crie um mod que mostre ao lado do spinner quantas chamadas de ferramenta você fez." Aprove os arquivos, lendo cada um, 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.
4. Peça ao Claude: "Mostre o register.js do mod que você criou e liste os eventos que ele escuta (on) e as chamadas que ele faz ao $." Compare com o exemplo desta aula.
5. (Opcional) No terminal integrado, clone o claude-code-playground, leia o código do token-weather e copie a pasta claude-code/mods/token-weather para ~/.claude/skills/. Abra uma sessão nova e veja a previsão acima da caixa de mensagem.

Documentação oficial: Mods overview (em inglês) e a parte sobre plugins no guia do app Desktop (em português).

Na prática

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

1. Atualize o app: no Mac, Claude → Check for Updates; no Windows, Help → Check for Updates.
2. Na aba Code, clique em + New. Na linha abaixo da caixa de mensagem, escolha Local e a pasta da sua página. Antes da primeira mensagem, escolha Manual no seletor de modo, na mesma linha.
3. Clique no +, ao lado da caixa de mensagem. Se o menu mostrar Plugins, abra Plugins e Manage plugins, olhe a lista e feche sem mudar nada. Se mostrar Add plugins, feche sem escolher nada.
4. Peça: "liste os plugins e os mods que eu instalei, em português simples, sem mudar nada". Confira: nenhum.
5. 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".

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 e desligar um mod: + → Plugins → Manage plugins. Para desligar todos os seus, peça ao Claude.

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