A referência completa são as declarações TypeScript para mods do Claude Code, que descrevem cada evento, método e elemento, com exemplos. A cópia no GitHub pode ser mais antiga que a versão do Claude Code que você tem instalada. Quando as duas divergirem, confie na cópia que o Claude Code grava para a sua versão.
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, chamandoon 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 emturn.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 faze.ceiling:askpara uma ferramenta de conector que sua organização definiu comoask, em sessões nas quais essa configuração chega ao Claude Code
tool.check, e.agentId e e.ceiling exigem o Claude Code v2.1.290 ou posterior.
O campo e.isReadOnly em tool.check
Em um hook tool.check, e.isReadOnly é true quando a ferramenta informa esta chamada como somente leitura. Caso contrário, o campo fica ausente, e não false. O valor é o próprio relato da ferramenta, então leia Verificar se uma chamada de ferramenta é somente leitura antes de aprovar uma chamada com base apenas neste campo.
Em tool.check, e.isReadOnly exige o Claude Code v2.1.304 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.
Enviar uma seção do system prompt ou uma descrição de ferramenta alterada com breakPromptCache
Para alterar uma seção ou uma descrição de ferramenta em uma conversa em andamento, chame $.ui.invalidate('prompt.section') ou $.ui.invalidate('tool.describe') para que seu hook seja executado novamente. Retorne { text, breakPromptCache: true } ou { description, breakPromptCache: true } a partir dele. Sem o campo, o Claude continua lendo o texto salvo com a conversa para uma seção ou uma ferramenta carregada antecipadamente até uma nova conversa ou uma compactação.
O texto alterado chega ao Claude no próximo turno, e o cache de prompt recomeça, então esse turno é mais lento e mais caro. O campo requer o Claude Code v2.1.321 ou posterior. Da v2.1.299 até a v2.1.321, uma conversa em andamento recebia o texto alterado no próximo turno.
Comandos e configuração
e.layers e e.source em settings.read
e.layers: um objeto{ source, settings }para cada origem em uso que contém configurações, da menor precedência para a maior. Consulte O que um hooksettings.readrecebe.e.source: a única origem que um mod solicitou, como em$.settings.read({ source: 'policy' }). Ausente na leitura do próprio Claude Code e em uma leitura das configurações mescladas
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:
Seu hook
agent.spawn também é executado quando um subagente que terminou ou foi interrompido está prestes a ser executado novamente, como quando o Claude envia a ele uma mensagem com a ferramenta SendMessage. Nesse evento, e.resume é { agentId }. Se o seu hook conta subagentes, ignore os eventos em que e.resume está definido, para que um subagente retomado não seja contado novamente.
Retorne { deny: reason } para recusar uma execução retomada. A execução não começa, e o subagente permanece como estava. Quando uma chamada de SendMessage solicitou a execução, o Claude lê a plugin declined the resume: seguido do seu motivo como o resultado dessa chamada. Se você passar um evento alterado para next em uma execução retomada, como um model diferente, o Claude Code ignora a alteração.
O evento para uma execução retomada requer o Claude Code v2.1.299 ou posterior. Antes da v2.1.299, seu hook
agent.spawn não era executado quando um subagente era retomado. Nessas versões, 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 hookui.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 chamadoclassic.<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, comofs.read, model.complete ou ui.open. Um hook em um deles pode retornar next(e), { deny: reason } ou { value }.
Alguns desses eventos também são disparados para as ações do próprio Claude Code, então verifique se next.origin.plugin é engine antes de recusar um deles.
Campos nas requisições http.fetch do próprio Claude Code
Em um hook http.fetch, um next.origin de { plugin: 'engine', tier: 'core' } marca uma das requisições do próprio Claude Code, como uma requisição ao modelo, e não uma chamada $.http.fetch de um mod. Onde a guarda integrada está carregada, seu hook não recebe esses eventos, exceto se o seu mod contar como um mod da sua organização.
Nesses eventos, e.init e o value para o qual next(e) resolve podem conter estes campos, entre outros:
Esses eventos e campos exigem o Claude Code v2.1.321 ou posterior.
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 dee.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. Uma sessão que não busca feature flags precisa da versão 2.1.304 ou posterior. 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
Paneou da faixa: desenhe atée.props.bodyColumns - Altura de um
Paneao lado da transcrição: quandoe.props.placementé'dock',e.props.scroll.bodyRowsé o número de linhas que o painel tem para a sua árvore - Altura de um
Paneacima do prompt: quandoe.props.placementé'inline', o painel cresce com a sua árvore até um limite, ebodyRowsé esse limite. Para solicitar um limite diferente, consulte o camporowsde$.ui.open.
Elementos
Elementos são os blocos de construção de uma árvore que um hookui.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- Hotkeys numéricos na faixa: um
hotkeynumé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 - Uma faixa recolhida: enquanto a faixa está recolhida, nem um atalho de
actionnem um hotkey pressiona um botão nela - Dois botões com o mesmo hotkey: quando dois dos seus botões em um mesmo desenho indicam o mesmo
hotkey, o posterior fica com ele. Para o botão de outro mod na mesma tecla, consulte Hotkeys não fazem nada. variant:primaryousecondary, e qualquer outro valor lança um erro. No terminal, um botãoprimaryé desenhado na cor de destaque, a menos que sejaplain.role:dismissmarca um botão de fechar, e qualquer outro valor lança um erro. Faça o fechamento no seuonPress. Em uma faixa que contém texto e uma fileira de botões, o aplicativo Desktop pode desenhar o primeiro botãodismissda fileira como seu próprio controle de fechar. O terminal desenha o botão como faria semrole.
Button pode conter children no lugar de um label:
- O que os children podem ser: strings e elementos
Text, como um nome seguido de um detalhe esmaecido ou um chip colorido. O Claude Code recusa qualquer outro elemento dentro de umButton. - Nomear o botão: o
labelnomeia o botão e, por padrão, é o texto de seus children. Dê umkeyou umlabela um botão com children que não sejam uma única string. - No terminal: os children são desenhados onde o label estaria, e um clique em qualquer ponto deles conta como um único pressionamento, então você pode transformar cada linha de uma lista em um único botão
- No aplicativo Desktop e na extensão do VS Code: o botão desenha seu
label
Um
Button com children que não sejam uma única string exige o Claude Code v2.1.295 ou posterior.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:positioncom seustop,left,rightebottom,alignSelf,borderDimColorehoverText:size,mono,tabularehoverButton:hotkey,plain,autoFocus,actionehover, então o usuário pressiona um botão ali com um clique, ou com Enter quando ele estiver com o foco. A extensão também ignoravarianterole.Code:language,path,startLine,formatewrap, então o código é desenhado sem cores nem números de linha, e um blocoformat: 'diff'mostra o texto bruto do diffInputeSelect:autoFocus, erowsem umInputSvg:isInteractive
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.
Passos de espaçamento de Box
As props de espaçamento de Box são gap, columnGap, rowGap, padding, margin e as formas de um lado e de um eixo de padding e margin, como paddingX e marginTop. Cada uma aceita um número de células do terminal, como gap: 1, ou um nome de passo, como gap: 'md'. No terminal e na extensão do VS Code, cada passo corresponde a esta quantidade de células:
Se você definir
gap, padding ou margin como um passo, o passo se aplica na horizontal e na vertical ao mesmo tempo. Por exemplo, no terminal e na extensão do VS Code, padding: 'md' equivale a duas células de cada lado e uma linha acima e abaixo.
Nomes de passos exigem o Claude Code v2.1.299 ou posterior. Em uma versão anterior, uma árvore que usa um nome de passo não é desenhada.
Props de tipografia de Text
Defina size, weight, mono ou tabular em um Text para pedir ao aplicativo que desenha sua árvore um tamanho de texto, um peso, uma fonte monoespaçada ou dígitos de largura igual. Antes de depender de uma prop, verifique o que o terminal e a extensão do VS Code fazem com ela. Se um aplicativo ignorar uma prop que você definiu, sua árvore ainda é desenhada ali, com o texto como se você tivesse omitido essa prop.
Essas quatro props exigem o Claude Code v2.1.299 ou posterior. Em uma versão anterior, uma árvore que define
size, weight, mono ou tabular não é desenhada.
Substituir bold por weight
bold em um Text foi descontinuado em favor de weight e ainda funciona. Para substituí-lo em um Text sem weight, altere bold: true para weight: 'semibold' para obter o mesmo resultado no Claude Code v2.1.299 ou posterior.
Em uma versão anterior à v2.1.299, uma árvore que define weight não é desenhada. Se você definir tanto bold quanto weight em um Text, bold não tem efeito.
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. Uma árvore acima do limite de aninhamento, de elementos, de células deRaster ou de bytes de Image não é desenhada.
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. Onde ela é carregada, ela é executada antes de todo mod que uma pessoa instala. 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 comandosclaude 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.