SpyBara
Go Premium

plugins/mods/overview.md 2026-09-30 23:00 UTC to 2026-10-01 21:59 UTC

This page contains 269 additions and 0 deletions.

2026
Thu 1 23:02

Visão geral de mods

Adicione painéis, comandos e regras de chamada de ferramentas ao Claude Code com um mod. Veja o que um mod pode fazer, como criar ou instalar um, e onde os mods são executados.

Um mod é um plugin que muda como o Claude Code se parece e se comporta. É feito de manipuladores de eventos em JavaScript ou TypeScript: Claude Code chama um quando um evento acontece, como uma chamada de ferramenta, um prompt enviado, ou uma parte da interface sendo desenhada, e o manipulador pode observar o evento, alterá-lo ou assumir o controle dele. Use um mod para adicionar um recurso próprio ao Claude Code, como um painel que mostra graficamente o quão cheio seu contexto está após cada solicitação. Para os arquivos em um mod e um exemplo completo, veja Como um mod funciona.

O que um mod pode fazer

Settings hooks, skills, linhas de status e servidores MCP funcionam de fora do Claude Code: cada um executa um script ou fornece ao Claude texto ou ferramentas. Um mod é executado dentro do Claude Code, então pode fazer coisas que eles não conseguem:

  • Desenhar uma interface que você pode usar: um painel ao lado da transcrição ou uma faixa acima do prompt, com abas, botões e campos de texto. Veja Desenhar na interface.
  • Redesenhar a própria interface do Claude Code: substituir ou reformatar partes que o Claude Code desenha, como a linha de uma chamada de ferramenta, o spinner ou o diálogo que o Claude faz perguntas. Veja Alterar o que o Claude Code já desenha.
  • Intervir em uma chamada de ferramenta ou uma solicitação: por exemplo, manter uma chamada de ferramenta enquanto você faz uma pergunta ao usuário, responder sem executar a ferramenta ou enviar uma solicitação para um modelo diferente. Veja Guardar ou alterar uma chamada de ferramenta e Seguir um turno.
  • Executar seu próprio código em um comando: um /command que executa sua função imediatamente, sem nenhum turno do Claude, mesmo enquanto o Claude está trabalhando. Veja Adicionar um comando ou uma ferramenta.
  • Compartilhar dados entre hooks: os hooks de um mod compartilham as variáveis em seu arquivo, então o que um hook registra, outro pode mostrar. Por exemplo, um hook pode contar chamadas de ferramenta enquanto outro mostra a contagem ao lado do spinner, ou um pode ler o uso de tokens de cada solicitação enquanto outro o mostra em gráfico em um painel. Veja Reagir a eventos.

Os mods funcionam no CLI do Claude Code e na aba Code do aplicativo Claude Desktop. Veja Onde os mods são executados para entender como eles se comportam em outros lugares, como na extensão VS Code, claude -p e sessões na nuvem. Se um settings hook, uma skill ou um servidor MCP já faz o que você precisa, compare-os antes de escrever um mod. Para gerenciar mods para uma organização, veja Gerenciar mods para sua organização.

Obter um mod

Você pode começar com um mod de três maneiras:

Instalar ou atualizar um mod

Um mod é instalado como um plugin, a partir de um marketplace. Forneça o nome do plugin, um @ e o nome do marketplace. Estes exemplos instalam um plugin chamado token-chart de um marketplace chamado your-org:

  • Em uma sessão do Claude Code, execute /plugin install token-chart@your-org.
  • No seu shell, execute claude plugin install token-chart@your-org.

Instalar plugins cobre marketplaces, escopos, a extensão VS Code e o aplicativo Desktop, e manter plugins atualizados, tudo isso se aplica a um plugin que contém um mod sem alterações.

Se você instalar ou atualizar um mod do seu shell enquanto uma sessão está aberta, execute /reload-plugins nessa sessão para carregá-lo. Caso contrário, ele carrega na próxima vez que você iniciar o Claude Code.

Decidir se confia em um mod

Um mod é código que é executado com suas permissões, dentro do Claude Code. Instale mods apenas de autores e marketplaces em que você confia.

O que um mod pode alcançar

Um mod é executado com suas permissões, então antes de instalar um, saiba o que ele tem acesso. Uma vez carregado, um mod pode:

  • Agir em sua máquina como você: ler e escrever arquivos em qualquer lugar que sua conta de usuário possa, iniciar programas e fazer solicitações de rede
  • Ler seus segredos: variáveis de ambiente e arquivos de configurações, incluindo uma chave de API que você mantém em qualquer um deles
  • Ver sua sessão: cada prompt que você envia e cada chamada de ferramenta que o Claude faz
  • Alterar sua sessão: reescrever um prompt ou uma chamada de ferramenta, enviar um prompt como se você o tivesse digitado, ou enviar uma mensagem para outra de suas sessões
  • Agir sem pedir a você: aprovar uma chamada de ferramenta antes de você ser perguntado
  • Gastar seu uso: chamar um modelo em seu plano ou chave de API

Um mod que aprova chamadas de ferramenta pode aprovar uma que uma regra ask solicitaria, ou que um de seus próprios hooks PreToolUse bloqueou. Estender permissões com hooks lista o que tal mod pode aprovar, incluindo quando pode aprovar uma chamada que uma regra deny recusa.

Um mod pode reformatar grande parte da interface do Claude Code, mas não o prompt de permissão. Não pode alterar o que um prompt mostra a você.

Listar o que um mod faz antes de instalá-lo

Antes de instalar um mod, você pode listar quais eventos ele conecta e o que pede ao Claude Code para fazer, como ler um arquivo ou fazer uma solicitação de rede, sem executá-lo. Obtenha os arquivos do plugin primeiro, por exemplo clonando seu repositório. Depois, no seu shell, execute claude plugin validate no diretório do plugin:

claude plugin validate ./some-mod

As linhas hooks: e calls: na saída listam os eventos que o mod manipula e o que pede ao Claude Code para fazer. Revisar o que um mod pode fazer mostra a saída e quais chamadas procurar.

Ativar ou desativar mods

Os mods requerem Claude Code v2.1.287 ou posterior, e estão ativados por padrão. No seu shell, execute claude --version para verificar e atualize o Claude Code se o seu for mais antigo.

Para desativar mods, escolha quantos parar e por quanto tempo. Para ativá-los novamente, desfaça a mesma alteração:

  • Um mod: desabilite ou desinstale seu plugin da aba Installed em /plugin
  • Cada mod instalado, para uma sessão: inicie o Claude Code com --safe-mode, que também deixa de fora suas outras personalizações
  • Cada mod que você instalou, em cada sessão: defina "disableAllHooks": true em ~/.claude/settings.json. Seus settings hooks e linha de status personalizada também param. O que sua organização gerencia continua funcionando.

Se você usar o Claude Code através de uma organização, um administrador também pode limitar quais mods carregam. Os administradores começam em Impedir que mods instalados pelo usuário sejam carregados.

Para descobrir se mods podem carregar para você, veja Verificar se mods podem carregar.

Ver quais mods uma sessão carregou

Para ver quais mods uma sessão de terminal carregou, execute /plugin no prompt do Claude Code. Uma linha atenuada sob as abas fornece a contagem e os nomes, como 1 mod active · first-mod. Se um mod que você instalou não estiver nomeado lá, veja Descobrir por que um mod não faz nada.

Como um mod funciona

Um mod é um plugin cujo código registra manipuladores de eventos, chamados hooks. O Claude Code executa um hook quando seu evento acontece, como quando o Claude chama uma ferramenta ou quando o spinner é desenhado. Um mod pequeno tem três arquivos:

first-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

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

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

// Claude Code chama isso uma vez quando o mod carrega
export function register(on) {
  // Executado cada vez que Claude está prestes a usar uma ferramenta
  on('tool.call', async ($, e, next) => {
    calls += 1
    // Peça ao Claude Code para desenhar a interface novamente, para que a nova contagem apareça
    $.ui.invalidate('ui.render')
    // Deixe a ferramenta ser executada normalmente
    return next(e)
  })

  // Executado cada vez que Claude Code desenha o spinner
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    // Mantenha o spinner do Claude Code, com a contagem adicionada após sua palavra
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
  })
}

O arquivo registra dois hooks, e ambos usam a variável calls no topo:

  • O hook tool.call é executado cada vez que o Claude está prestes a usar uma ferramenta. Adiciona um a calls, pede ao Claude Code para desenhar a interface novamente e deixa a ferramenta ser executada normalmente.
  • O hook ui.render é executado cada vez que o Claude Code desenha o spinner. Mantém o próprio spinner do Claude Code e adiciona a contagem após a palavra.

Esta gravação mostra o mod em ação. Observe a linha do spinner acima da caixa de prompt: enquanto o Claude lista um diretório e lê dois arquivos, ele lê Thinking · tool calls: 1…, depois 2…, depois 3….