Referência de mods

Consulte qualquer evento que um mod pode tratar, método da API de mods que ele pode chamar ou ponto de renderização em que ele pode desenhar. As entradas abrangem a CLI do Claude Code e o aplicativo Desktop a partir da v2.1.290, e a extensão do VS Code a partir da v2.1.299. Cada entrada fornece o nome e uma descrição de uma linha, e aponta para a seção do guia que a explica, quando houver.

​

Arquivos

Um mod é um diretório de plugin com estes arquivos: register recebe on e options. options contém os valores dos campos userConfig que o manifesto declara, com os valores padrão preenchidos.

​

A função de hook

Um mod registra cada um de seus hooks, que são manipuladores de eventos, chamando on dentro de register. on recebe o nome do evento, um matcher opcional, que é um filtro sobre os campos do evento, e o hook, como em on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e)). on retorna um registro com um método, .catch(handler), que define o manipulador de erros do hook.

​

Eventos

Os eventos estão agrupados pelo assunto de que tratam, cada um com quando é disparado e o que um hook nele pode retornar. Hooks em turn.step e process.spawn são geradores assíncronos, e os outros hooks são funções assíncronas. A última coluna de cada tabela usa uma notação abreviada. next(e) repassa o evento sem alterações. next({ ...e, text }) repassa uma cópia com o campo indicado alterado, como em next({ ...e, text: e.text.trim() }). Um objeto responde ao evento sem chamar next, e uma palavra como reason representa uma string que você escreve, como em { deny: 'Use the file tools.' }.

​

Ferramentas

Eventos de ferramenta são disparados em torno de cada chamada de ferramenta que o Claude faz, desde a descrição que o Claude lê até a decisão sobre se a chamada é executada:

​

Campos de agente e de organização em tool.check

Em um hook tool.check, leia estes campos para distinguir a chamada de um subagente da chamada da conversa principal, e para ver se sua organização exige aprovação para uma ferramenta de conector:

• e.agentId: definido quando um subagente ou um colega de equipe em processo faz a chamada, e ausente quando é a conversa principal que a faz
• e.ceiling: ask para uma ferramenta de conector que sua organização definiu como ask, em sessões nas quais essa configuração chega ao Claude Code

Em tool.check, e.agentId e e.ceiling exigem o Claude Code v2.1.290 ou posterior.

​

Prompts e o que o Claude lê

Eventos de prompt abrangem o texto que o usuário digita e o texto que o Claude Code envia ao Claude por conta própria, como o system prompt e lembretes:

​

Campos de origem e de frontmatter em skill.prompt

Em um hook skill.prompt, você pode ler estes campos junto com o nome da skill em e.skill e o texto que o Claude lê em e.text: Um hook pode passar um text ou um frontmatter alterado para next: os hooks depois dele leem ambos, e o Claude lê o text final. Um hook que altera qualquer outro campo falha. Em skill.prompt, e.source, e.pluginName, e.path, e.frontmatter e e.frontmatterProblem exigem o Claude Code v2.1.299 ou posterior.

​

Comandos e configuração

Eventos de comando e de configuração são disparados quando um comando é executado ou listado, e quando uma linha de /config é exibida ou alterada:

​

Turnos

Eventos de turno acompanham uma resposta do início ao fim, incluindo cada requisição ao modelo dentro dela:

​

Sessão

Eventos de sessão marcam o início, o fim e a compactação da sessão, e a troca de mensagens com outras sessões:

​

Subagentes

Eventos de subagente são disparados quando um tipo de subagente é oferecido ao Claude e quando um subagente ou um colega de uma equipe de agentes está prestes a iniciar: Quando o Claude retoma um subagente com a ferramenta SendMessage, seu hook agent.spawn não é executado novamente. Para recusar as chamadas de SendMessage que retomam um subagente, faça a correspondência dessa ferramenta em um hook tool.call.

​

Interface

Eventos de interface são disparados quando o Claude Code desenha um ponto de renderização e quando o usuário usa um controle que um mod desenhou. Desenhar na interface mostra o que um hook ui.render retorna:

​

Outros mods

Estes eventos permitem que um mod atue sobre outros mods à medida que são carregados, para recusar um deles ou alterar a API de mods que ele recebe: Quando o hook de outro mod chama um método em um namespace que você adicionou em engine.create, as chamadas $ do seu método são executadas no contexto desse hook até que todos os hooks nesse evento retornem. Por exemplo, um caminho relativo é resolvido em relação ao diretório de trabalho desse hook, e $.prompt.submit é rejeitado enquanto o turno está aguardando esse hook. As chamadas que seu método faz depois disso são executadas no próprio contexto do seu mod.

​

Telemetria

Eventos de telemetria são disparados para os registros de uso que o Claude Code registra em log:

​

Eventos de hooks de configuração

Cada evento de hook de configuração é um evento chamado classic.<Event>, como classic.Stop ou classic.PostToolUse. e é o JSON de stdin do hook.

​

Chamadas à API de mods

Cada método da API de mods também é um evento, nomeado pelo seu namespace e método, como fs.read, model.complete ou ui.open. Um hook em um deles intercepta chamadas dos mods executados depois dele e pode retornar next(e), { deny: reason } ou { value }.

​

Métodos da API de mods

A API de mods é o argumento $ que todo hook recebe. Seus métodos estão agrupados em namespaces, como $.ui. Esta tabela lista os métodos de cada namespace pelo nome, então open na linha de $.ui é a chamada $.ui.open(...). Os guias mostram os mais comuns em uso, e os tipos para o seu build documentam cada método com um exemplo.

​

Pontos de renderização

Um ponto de renderização é um ponto de extensão na interface do Claude Code. Cada linha é um valor de e.component em um hook ui.render, com os campos de e.props e os aplicativos que o renderizam. e.surface indica o aplicativo que está desenhando, como terminal, desktop ou vscode. Alterar o que o Claude Code já desenha mostra o que um hook pode fazer em um ponto, com um exemplo de cada opção. A renderização na extensão do VS Code requer a versão 2.1.299 ou posterior da extensão e uma sessão que busque feature flags. Desenhar na extensão do VS Code lista o que a extensão desenha de forma diferente. e.viewport contém columns, rows e isFullscreen. No terminal e no aplicativo Desktop, ele está ausente até que o aplicativo tenha medido sua janela. Nesses casos, seu rows é a altura da janela inteira, não do seu painel. Na extensão do VS Code, ele está sempre presente. Para ajustar uma árvore ao seu ponto, leia estas props no hook:

• Largura de um Pane ou da faixa: desenhe até e.props.bodyColumns
• Altura de um Pane ao lado da transcrição: quando e.props.placement é 'dock', e.props.scroll.bodyRows é o número de linhas que o painel tem para a sua árvore
• Altura de um Pane acima do prompt: quando e.props.placement é 'inline', o painel cresce com a sua árvore até um limite, e bodyRows é esse limite. Para solicitar um limite diferente, consulte o campo rows de $.ui.open.

Uma árvore mais alta que o painel rola como um todo.

​

Elementos

Elementos são os blocos de construção de uma árvore que um hook ui.render retorna, e você os obtém de $.ui.resolve(e). Construir uma árvore a partir de elementos mostra os mais comuns com a forma como o terminal os desenha, e a galeria da interface tem capturas de tela da maioria. Uma marca de seleção significa que o aplicativo pode desenhar o elemento. Mais regras de Button: action indica uma das próprias ações de atalho de teclado do Claude Code, e o atalho do usuário para ela pressiona o botão quando esse atalho é um acorde ou uma tecla com modificador. Um hotkey numérico em um botão na faixa também é acionado quando o usuário digita apenas esse dígito em um prompt vazio e faz uma pausa. Quando dois botões em um mesmo desenho indicam o mesmo hotkey, o posterior fica com ele. autoFocus aceita apenas true em qualquer controle, então omita a prop para deixá-lo desativado. A extensão do VS Code ignora algumas props de elementos e desenha o elemento como se você as tivesse omitido:

• Box: position e hover
• Button: hotkey, plain, autoFocus e action, então o usuário pressiona um botão ali com um clique, ou com Enter quando ele estiver com o foco
• Code: language, path, startLine, format e wrap, então o código é desenhado sem cores nem números de linha, e um bloco format: 'diff' mostra o texto bruto do diff
• Input e Select: autoFocus

​

Estilos de borda de Box

Para desenhar uma borda ao redor de um Box, defina seu borderStyle como um destes nomes, como em borderStyle: 'round'. Cada linha informa o que o terminal desenha para esse nome e mostra a borda superior. Um Box cujo borderStyle indica qualquer outro nome, como 'rounded', é desenhado sem borda.

​

Limites

Hooks e chamadas à API de mods são executados sob limites de tempo e de tamanho. O Claude Code ignora um hook que excede um limite de tempo.

​

Configurações e variáveis de ambiente

Estas são as configurações e variáveis de ambiente que afetam os mods. A coluna Onde indica de qual arquivo de configurações ou ambiente cada uma é lida: sec-default@builtin é uma guarda integrada ao Claude Code, listada como cc-plugin-sec-default em /plugin e no log de depuração. Ela é carregada antes de todo mod que uma pessoa instala em uma máquina com configurações gerenciadas, ou para um usuário conectado com um plano Team ou Enterprise. Se prependPlugins gerenciado estiver definido, a guarda só é carregada quando essa lista a indica, na posição listada. Seu código-fonte está no diretório mods/sec-default do repositório do Claude Code.

​

Comandos

Estes comandos e flags carregam, inspecionam e testam um mod. Os comandos claude são executados no seu shell e os comandos / no prompt do Claude Code. Na tabela, <directory> representa um caminho que você digita, como em claude plugin validate ./first-mod. Colchetes marcam um argumento opcional.