🧬 O que é um mod por dentro

Sem mods, o Claude Code faz sempre a mesma coisa: recebe o seu pedido, chama o modelo, roda ferramentas e desenha a conversa. Um mod entra no meio desse caminho.

Ele pode observar (contar quantos arquivos o Claude leu), desenhar (uma faixa acima do prompt, um painel do lado), acrescentar (um comando /meu-comando, uma ferramenta nova para o modelo) ou mudar o que acontece (perguntar antes de um rm, trocar o modelo de um subagente).

Como ler o desenho: a linha azul é o caminho normal de um pedido. Os pontos verdes são eventos. O mod não fica "rodando ao lado": ele só age quando um desses pontos acontece e a função dele é chamada.

Quatro coisas estendem o Claude Code, e é fácil misturar. A pergunta que separa: quem executa e quando.

O hook clássico é um comando de shell que o settings.json chama. A skill é texto que o modelo lê. O MCP é um servidor à parte. O mod é código que roda dentro do Claude Code, com acesso aos eventos e à tela.

O que olhar na tabela: só a primeira linha tem "sim" na coluna da tela. Se o que você quer é ver alguma coisa enquanto o Claude trabalha, é mod. Se é só bloquear um comando, um hook clássico pode bastar.

Todo mod exporta uma função register. O Claude Code chama essa função uma vez quando o módulo carrega (e de novo a cada recarga). Ela não faz o trabalho: ela pendura os hooks.

Recebe dois argumentos. on é a função que pendura um hook num evento. options traz os valores que a pessoa escolheu para as opções que o mod declarou no plugin.json (você vê no módulo 1.2).

// Minimal teaching example. Counter is scoped to this module instance.
export function register(on) {
  let count = 0;
  on("session.start", async ($, e, next) => {
    const result = await next(e);
    count = 0;
    await $.command.register({ name: "readcount", description: "Show successful reads observed by this example" });
    return result;
  });
  on("tool.call", { tool: "Read" }, async ($, e, next) => {
    const result = await next(e);
    if (!result.isError && result.deny === undefined) count += 1;
    return result;
  });
  on("command.run", { command: "readcount" }, async () => ({ text: `Successful reads observed: ${count}` }));
}

Todo hook tem a mesma forma: ($, e, next). Decorar esses três é metade do curso.

$ é tudo o que o mod pode pedir ao Claude Code. e é o que aconteceu. next passa a vez para os outros plugins e, por fim, para o comportamento normal do Claude Code.

Como ler o desenho: o hook está no meio do caminho. O e chega da esquerda, o $ desce de cima com tudo o que o mod pode usar, e o next é a porta para a direita. Quem não chama next responde no lugar de todo o resto (trilha 2).

O módulo do mod roda num ambiente próprio, sem DOM e sem Node. Não existe require, process.env, fetch nem document. Tudo o que está fora do mod chega pelo $.

Isso é uma vantagem: o que o mod faz fica visível. Quer ler um arquivo? $.fs. Rodar um comando? $.process. Guardar algo? $.store. O claude plugin validate lista exatamente o que o mod chama (você vê no módulo 1.4).

O curso usa dois kits abertos como material. Você clona os dois e roda os exemplos de verdade. Quem acompanha os exemplos é o Rafa, 34, dev numa agência pequena: ele quer ver o que o Claude toca no repositório e não perder trabalho entre sessões.

Como ler o desenho: cada degrau usa o anterior. Na T1 o mod carrega e responde um comando; na T2 ele reage a eventos e guarda estado; na T3 ele desenha; na T4 ele controla o fluxo, passa nos testes e vai para um marketplace.