SpyBara
Go Premium

plugins/mods/overview.md 2026-10-22 22:58 UTC to 2026-10-23 22:59 UTC

This page contains 56 additions and 56 deletions.

2026
Thu 1 23:59 Fri 2 22:59 Tue 6 23:59 Thu 8 22:58 Wed 14 22:58 Thu 15 23:58 Mon 19 23:58 Tue 20 23:00 Thu 22 22:58 Fri 23 22:59

Visão geral de mods

Adicione painéis, comandos e regras de chamada de ferramenta 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.

[!NOTE]

Os hooks existentes do Claude Code também são executados em eventos, como um comando shell, uma solicitação HTTP ou um prompt que você configura em um arquivo de configurações. Os manipuladores de um mod são funções que são executadas dentro do Claude Code em vez disso. Claude Code chama ambos os tipos de hooks: nessas páginas, "hook" significa um manipulador de um mod, e o tipo de arquivo de configurações é um "settings hook".

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, na aba Code do aplicativo Claude Desktop e na extensão do VS Code. Veja Onde os mods são executados para entender como eles se comportam em outros lugares, como em claude -p e em sessões na nuvem. Se um hook de configuração, 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

Para começar com um mod:

Instalar ou atualizar um mod

[!WARNING]

Um mod é código que é executado com suas permissões. Pode ler e escrever seus arquivos, iniciar processos e fazer requisições de rede. Instale mods apenas de autores e marketplaces em que você confia. Veja Decidir se confia em 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.

Experimentar um mod de exemplo

A Anthropic compartilha mods de exemplo no diretório claude-code/mods do repositório claude-code-playground. Cada um é um plugin completo, e seu README explica como foi construído. O repositório os compartilha como estão, sem suporte.

  • token-weather: desenha uma previsão da sua janela de contexto acima do prompt
  • blast-radius: retém um comando de shell arriscado, como rm -rf ou um force push, e mostra o que ele alteraria, com botões para prosseguir ou cancelar
  • replay-theater: adiciona um comando /replay que percorre as edições de arquivos que o Claude fez no último turno

Um mod de exemplo é executado com suas permissões. Para ver o que um deles faz antes de carregá-lo, liste seus hooks e chamadas.

Para experimentar um, clone o repositório e carregue o diretório do mod para uma sessão com --plugin-dir. Para confirmar que o mod foi carregado, verifique quais mods a sessão carregou.

Para mantê-lo, adicione o diretório claude-code/mods do clone como um marketplace e, em seguida, instale o mod a partir de claude-code-playground-mods. O marketplace aponta para o seu clone, então o mod deixa de ser carregado se você movê-lo ou excluí-lo.

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 requisiçõ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

Os mods não são executados em sandbox. Se você ativar o sandboxing, o sandbox isola os comandos Bash que o Claude executa, e um processo que um mod inicia é executado fora dele.

Com configurações gerenciadas ou um /login de Team ou Enterprise como credencial da sessão, por padrão a aprovação de um mod não faz uma chamada passar por suas regras ask ou hooks PreToolUse. Sem nenhum dos dois, um mod pode aprovar uma chamada que uma regra ask solicitaria, ou que seu hook PreToolUse bloqueou. Para verificar quando um mod também pode aprovar uma chamada que uma regra deny recusa, consulte Estender permissões com hooks.

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 manipula e o que pede ao Claude Code para fazer, como ler um arquivo ou fazer uma requisiçã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 estão ativados por padrão. No terminal, use o Claude Code v2.1.287 ou posterior. O aplicativo Desktop inclui sua própria cópia do Claude Code, e os mods funcionam nele a partir da v2.1.286. Verifique a versão no local onde você usa mods:

  • Terminal: no seu shell, execute claude --version. Se a sua for mais antiga, atualize o Claude Code.
  • Aplicativo Desktop: em uma sessão local na aba Code, digite /status e leia a linha Claude Code, que mostra uma versão como 2.1.286. Se a sua for mais antiga, atualize o aplicativo Desktop.

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 desativa 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.

disableAllHooks e o allowManagedModsOnly da sua organização param um mod e mantêm o restante do seu plugin no lugar: o plugin permanece instalado, e suas skills, comandos, agentes e servidores MCP são carregados. Outras configurações e flags têm um alcance maior. disableAllHooks e O que é executado sob allowManagedHooksOnly listam o que cada uma faz com um plugin e com seus settings hooks.

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

[!NOTE]

Se você definiu CLAUDE_CODE_ENABLE_FUNCTION_HOOKS durante acesso antecipado, remova-o. Claude Code v2.1.287 e posterior o ignora, então defini-lo como 0 não mantém mods desativados.

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….

// The count, shared by the two hooks below
let calls = 0

// Claude Code calls this once when the mod loads
export function register(on) {
  // Runs each time Claude is about to use a tool
  on('tool.call', async ($, e, next) => {
    calls += 1
    // Ask Claude Code to draw the interface again, so the new count shows
    $.ui.invalidate('ui.render')
    // Let the tool run as usual
    return next(e)
  })

  // Runs each time Claude Code draws the spinner
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    // Keep Claude Code's spinner, with the count added after its word
    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….