SpyBara
Go Premium

plugins/mods/reference.md 2026-11-08 22:58 UTC to 2026-11-09 23:02 UTC

This page contains 14 additions and 4 deletions.

2026
Wed 4 23:59 Mon 9 23:02 Tue 10 21:57

Referência de mods

Referência completa para mods do Claude Code: estrutura do módulo de hooks, eventos, métodos da API de mods, pontos de renderização, elementos por superfície, limites e configurações.

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.

[!NOTE]

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:

Arquivo Obrigatório Conteúdo
.claude-plugin/plugin.json Sim O manifesto do plugin. Mods não adicionam campos obrigatórios.
hooks/hooks.json Sim modules: um array com um caminho, relativo a este arquivo, para o módulo de hooks, como em "modules": ["./register.js"]. Também pode conter hooks de configuração em hooks.
O módulo de hooks, como hooks/register.js Sim O ponto de entrada do mod. Exporta register(on, options). Nomeado .js, .mjs, .cjs, .jsx, .ts, .mts, .cts ou .tsx. Um módulo ES.
types/index.d.ts, a menos que types no manifesto indique outro caminho Quando o mod usa $.state ou adiciona um namespace à API de mods Declara os valores de PluginState e qualquer namespace que o mod adiciona. Para omitir types do manifesto, você precisa da v2.1.299 ou posterior.
Arquivos cujos nomes terminam em .test.ts ou .test.tsx Não Testes que o claude plugin test executa

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.

Argumento O que é
$ A API de mods: todos os métodos em métodos da API de mods. Escreva cada chamada por completo, namespace e depois método, como em $.fs.read('notes.md').
e A entrada do evento, como dados simples profundamente congelados. Para alterá-la, passe uma cópia para next.
next(e) O próximo manipulador, como em um middleware. Executa os hooks depois deste e, em seguida, o comportamento do Claude Code. Resolve para o resultado do evento.
next.signal Um AbortSignal que é abortado quando o evento é abandonado
next.origin { plugin, tier } de quem disparou o evento. O próprio Claude Code é { plugin: 'engine', tier: 'core' }. O tier de um mod é seu grupo de prioridade na ordem em que os mods são executados: prepend, user, append ou builtin.
next.budget O limite de tempo do hook em milissegundos: next.budget.ms é o limite inteiro e next.budget.remainingMs é o que resta agora
next.to(e, tier) Pula para um tier posterior, que é append, builtin ou core. next.to(e, 'append') pula os mods que um usuário instalou. Somente um mod em prependPlugins ou appendPlugins pode chamá-lo.
next.error Somente em um manipulador .catch. kind é throw ou timeout quando o hook falhou, e message é o texto do erro. kind é re-entry quando o hook foi ignorado porque o evento veio de dentro de uma chamada à API de mods feita por esse hook ou pelo código do seu mod fora de seus hooks. re-entry exige o Claude Code v2.1.292 ou posterior.
next.error.cause Definido somente quando kind é re-entry. rewritten se um hook tool.call ou PreToolUse alterou a chamada à API de mods da qual o evento veio, ou se um hook agent.spawn alterou um agente iniciado por essa chamada. lent quando um método que outro mod adiciona à API de mods disparou esse evento, a menos que rewritten também se aplique. lent exige o Claude Code v2.1.292 ou posterior e rewritten, v2.1.300 ou posterior.
next.called Somente em um manipulador .catch. true quando o hook havia chamado next.

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:

Evento Dispara quando Um hook pode retornar
tool.call Uma ferramenta está prestes a ser executada next(e), { deny: reason } ou { result }
tool.check O Claude Code decide se uma chamada de ferramenta pode ser executada, após os hooks tool.call e PreToolUse. next(e) resolve para a decisão a que chegaram as regras, o modo de permissão e esses hooks. next(e) ou { decision }, com decision definido como allow, ask ou deny e um reason opcional
tool.describe Uma vez para cada ferramenta, quando sua descrição é enviada pela primeira vez ao Claude. Uma segunda vez para uma ferramenta MCP quando o Claude a carrega por meio da busca de ferramentas, com e.description definido como o texto que o Claude lê para a ferramenta carregada. { description }, opcionalmente com isDeferred definido como true para colocar a ferramenta por trás da busca de ferramentas ou false para carregá-la antecipadamente. Adicione breakPromptCache: true para enviar uma descrição alterada no próximo turno.

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:

Em 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:

Evento Dispara quando Um hook pode retornar
prompt.submit Um prompt é enviado next({ ...e, text }), next({ ...e, context }) ou { drop: reason }
prompt.fill, prompt.suggest Um texto está prestes a entrar na caixa de prompt como rascunho ou como uma sugestão esmaecida next(e) com o texto alterado
prompt.edit O usuário edita a caixa de prompt next(e)
prompt.autocomplete O usuário digita na caixa de prompt e uma palavra termina no cursor. e.token é essa palavra. O Claude Code não espera pelo hook: suas próprias linhas de preenchimento automático aparecem primeiro. { suggestions }, uma lista de linhas { text, label, description } exibidas abaixo das do próprio Claude Code. Escolher uma linha escreve seu text sobre a palavra.
prompt.compose O Claude Code renderiza um system prompt { sections }, uma lista de { id, text, scope } na ordem em que são enviadas
prompt.section Uma vez para cada seção nomeada do system prompt. e.name é o id da seção em prompt.compose. { text }, ou { text: null } para omitir a seção. Adicione breakPromptCache: true para enviar uma seção alterada no próximo turno.
prompt.context Uma vez para cada conversa, para o contexto enviado com a primeira mensagem { blocks }
prompt.attachment O Claude Code adiciona uma mensagem própria para o Claude, como um lembrete. e.type indica o tipo e, para os tipos que as declarações de tipos declaram, e.detail contém os fatos a partir dos quais o texto foi escrito. { text }, ou { text: null } para omiti-la
prompt.mention O Claude Code está prestes a ler um arquivo que um prompt menciona com @. Requer o Claude Code v2.1.290 ou posterior. next({ ...e, path }) para ler um arquivo diferente, ou { deny: reason }
skill.prompt O texto de uma skill é expandido para o Claude { text }
attribution.text O Claude Code compõe o texto de atribuição de um commit ou pull request { text }

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:

Campo Tipo O que contém
e.source string Quem fornece a skill: policySettings, userSettings ou projectSettings para uma skill no local corporativo, pessoal ou de projeto, respectivamente. Outras origens fornecem uma palavra como plugin, mcp, syncedSkills ou built-in.
e.pluginName string O nome do plugin, para uma skill cujo e.source é plugin
e.path string O caminho absoluto do arquivo SKILL.md da skill, ou do seu arquivo .md para uma skill escrita como um arquivo de comando. Ausente quando a skill não tem arquivo nesta máquina, como no caso de uma skill integrada.
e.frontmatter object O frontmatter do arquivo da skill, como dados simples
e.frontmatterProblem string O motivo pelo qual e.frontmatter não contém o frontmatter do arquivo ou uma de suas chaves, como em is a list or a single value, not a table. Ausente quando e.frontmatter contém o frontmatter inteiro ou a skill não tem nenhum.

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

Evento Dispara quando Um hook pode retornar
command.run Um comando está prestes a ser executado { text }, {} ou next(e)
command.describe Uma vez para cada comando, para a lista de comandos { description, argumentHint, isHidden }
config.set Uma linha de /config está prestes a mudar next({ ...e, value }) ou { deny: reason }
config.describe Uma vez para cada linha de /config { label, description, isHidden }
settings.read Um mod chama $.settings.read, ou o Claude Code monta as configurações mescladas da sessão. Requer o Claude Code v2.1.304 ou posterior na leitura do próprio Claude Code e para e.layers next(e), { value } ou { deny: reason }

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 hook settings.read recebe.
  • 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:

Evento Dispara quando Um hook pode retornar
turn.start Um turno começa next(e)
turn.step Uma requisição está prestes a ir para o modelo yield* next(e), ou next({ ...e, model }), next({ ...e, effort })
turn.complete Um turno terminou next(e), ou { text } para mostrar uma linha abaixo da resposta

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:

Evento Dispara quando Um hook pode retornar
session.start Uma vez para cada mod carregado, antes do primeiro prompt, e novamente após um recarregamento desse mod. Não após /clear, /resume ou /branch. next(e)
session.end A sessão termina, ou /clear, /resume ou /branch é executado. e.reason é clear, resume, logout, prompt_input_exit ou other. /branch informa resume. next(e)
session.compact A conversa está prestes a ser compactada { skip: reason }
session.receive, session.send Uma mensagem chega de, ou está prestes a ir para, outro agente ou sessão. Consulte Enviar e receber mensagens entre sessões. { consumed: reason } para receive, { isDelivered: false, reason } para send
session.append Uma vez para cada linha que a conversa mantém, como um prompt, um bloco de resposta, um resultado de ferramenta ou um aviso, antes de ser armazenada next({ ...e, message }) com um message.content alterado, para reescrever os blocos de texto da linha ou o content de um bloco tool_result nela
session.attach, session.detach Outro aplicativo se conecta à sessão ou se desconecta dela next(e)
session.measure Após cada turno e quando o percentual usado de um limite do plano muda next(e)

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:

Evento Dispara quando Um hook pode retornar
agent.offer Um tipo de subagente é oferecido ao Claude { isOffered: false } para retê-lo
agent.spawn Um subagente ou um colega de uma equipe de agentes está prestes a iniciar, ou um subagente que terminou ou foi interrompido está prestes a ser executado novamente. Para um colega de equipe, e.isTeammate é true. Para uma execução retomada, e.resume é definido. next({ ...e, model }) para escolher o modelo de um que está iniciando, ou { deny: reason }

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.

[!NOTE]

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 hook ui.render retorna:

Evento Dispara quando
ui.render Um ponto de renderização está prestes a ser desenhado
ui.resolve Os mods são carregados, uma vez para cada aplicativo, ponto de renderização e mod. O resultado é a tabela de elementos que $.ui.resolve(e) lê.
ui.press, ui.input, ui.select Um Button, Input ou Select que um mod desenhou é usado
ui.focus, ui.scroll O controle em foco ou a posição de rolagem de um painel ou da faixa está prestes a mudar
ui.close Um painel está prestes a fechar. e.id é o painel e e.origin.kind é plugin, person ou unload.
ui.message Um elemento Client envia dados para o seu mod
ui.fault Um elemento Client que seu mod desenhou falhou ao carregar, desenhar ou executar. e.phase é load, render ou run, e e.reason é a mensagem de erro. Requer o Claude Code v2.1.289 ou posterior.

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:

Evento Dispara quando Um hook pode retornar
plugin.register Um módulo de hooks está prestes a ser carregado. e.uses lista seus eventos, chamadas à API de mods, variáveis de ambiente e estado, como o claude plugin validate os imprime. Cada chamada é escrita sem o prefixo $., como fs.read. { refuse: reason }
engine.create A API de mods está sendo construída para este mod Uma API de mods alterada, para adicionar um namespace. Um mod fora do nível user também pode reter um.

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:

Evento Dispara quando Um hook pode retornar
telemetry.log, telemetry.mark Um registro de telemetria está prestes a ser registrado em log, ou um uso de um recurso é marcado. Em um mod que você instala, dê a um hook de telemetria o filtro { to: 'collector' }, como em on('telemetry.log', { to: 'collector' }, hook). Sem o filtro, o mod falha no claude plugin validate. * não corresponde a esses eventos. next(e) ou { deny: reason }

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.

Namespace Métodos
$.plugin name, root: o nome e o diretório deste plugin
$.ui resolve, invalidate, open, close, panes, place, focus, scroll, toast, notify, status, log, notice, ask, copy, selection, blit, view. view exige o Claude Code v2.1.300 ou posterior e place, a v2.1.314 ou posterior.
$.theme set, clear: define um plano de fundo para o aplicativo Desktop ou móvel desenhar e remove o plano de fundo. Exige o Claude Code v2.1.319 ou posterior.
$.command register, run, list
$.tool register, call, check, list
$.agent register, spawn, list. list() retorna os subagentes e colegas de equipe desta sessão, cada um com um status de pending, running, waiting, idle, completed, failed ou killed, sendo que idle e waiting exigem o Claude Code v2.1.289 ou posterior.
$.model complete, fork, classify
$.prompt submit, read, fill, suggest, compose. O Claude lê o texto de submit({ text }) após uma frase que indica o seu mod como remetente. submit({ text, asUser: true }) envia o texto como se fossem palavras do próprio usuário, sem essa frase.
$.turn abort
$.session messages, cwd, root, model, turns, id, repo, surfaces, usage, version, compact, send, append, authorize. usage() retorna { startedAt, context, rateLimits, cost }: context tem tokens, window e percent, e rateLimits é uma lista de { kind, percentUsed, resetsAt }.
$.config list, set
$.settings read
$.env get, set
$.fs read, write, list, exists, stat, ancestors. write não é atômico: ele substitui o conteúdo do arquivo no local, então outro processo pode ler um arquivo parcialmente gravado. Mantenha dados que várias sessões alteram em $.store.
$.store get, set, delete, keys. Um armazenamento de chave-valor compartilhado por todas as sessões na máquina. Consulte Salvar a partir de mais de uma sessão.
$.state Estado reativo: get, set, com os auxiliares atom, read, update, derive e memberOf importados de claude-code
$.clock now, sleep, after, every
$.http fetch
$.process run, spawn
$.mcp call, connect. connect(server) conecta um servidor MCP que o manifesto do seu próprio plugin lista.
$.audio play, speak
$.telemetry log, mark. Um registro só é enviado quando o Claude Code ou um mod integrado faz a chamada.

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

Ponto e.props e.requestId Renderizado em
Pane title, isFocused, bodyColumns, placement, scroll, view O id do painel Terminal, Desktop, VS Code
AbovePrompt hasSurvey, isWorking, maxRows, bodyColumns, scroll, view Uma instância Terminal, Desktop
Placed id, plugin, onScreen O requestId que $.ui.place retornou Terminal
Backdrop id, plugin, glass, colorScheme backdrop Superfícies desktop e mobile. Seu hook é executado quando o aplicativo Desktop ou mobile solicita desenhar um plano de fundo.
UserMessage text, origin, isExpanded e task ou from conforme a origem O id da mensagem Terminal, Desktop, VS Code
AssistantMessage O texto da resposta O id da mensagem Terminal, Desktop, VS Code
ToolUse, ToolResult, ToolGroup O nome, a entrada e o resultado da ferramenta O id da chamada de ferramenta Terminal, Desktop, VS Code
CommandOutput command, text O id da mensagem Terminal, Desktop
AskUserQuestion A pergunta e as opções O id da chamada de ferramenta Terminal, Desktop, VS Code
ToolProgress kind O id da chamada de ferramenta Terminal
Spinner word, message, suffix, mode O id do agente Terminal, Desktop, VS Code
TurnDuration word, durationMs O id da mensagem Terminal
InfoNotice text, command O id da mensagem Terminal
SessionMode modes Uma instância Terminal, Desktop
PromptHint isDraft, isWorking, hint Uma instância Terminal, Desktop

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.

Elemento Props principais Terminal Desktop VS Code
Box key, layout flex, gap, padding, margin, width, height, minWidth, minHeight, borderStyle, borderColor, borderDimColor, backgroundColor, position, top, left, right, bottom, overflow, display, hover ✓ ✓ ✓
Text color, backgroundColor, bold, italic, underline, strikethrough, dimColor, inverse, wrap, size, weight, mono, tabular, hover ✓ ✓ ✓
Button key, label, children, onPress, hotkey, plain, dimColor, autoFocus, action, variant, role, hover ✓ ✓ ✓
Link href, label. Consulte Limites. ✓ ✓ ✓
Code source, language, path, startLine, format, wrap ✓ ✓ ✓
Markdown text, key, dimColor, onLinkPress, pressableLinks ✓ ✓ ✓
Input key, label, placeholder, value, submitLabel, rows, onSubmit, onInput, autoFocus ✓ ✓ ✓
Select key, label, options, value, onSelect, autoFocus ✓ ✓ ✓
Svg um source de marcação SVG de até 131.072 caracteres, texto alt, width, height e isInteractive ✓ ✓
Client module, key, props, width, height, flexGrow ✓ ✓
Raster key, columns até 512, rows até 256, cells. Consulte Desenhar uma grade de células coloridas. ✓
Image key, um source como bytes PNG ou RGBA de até 2 MiB, ou um caminho de arquivo, columns e rows até 255, e texto alt. Consulte quais terminais o desenham. ✓

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 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
  • Uma faixa recolhida: enquanto a faixa está recolhida, nem um atalho de action nem um hotkey pressiona um botão nela
  • Dois botões com o mesmo hotkey: quando dois botões em um mesmo desenho indicam o mesmo hotkey, o posterior fica com ele
  • variant: primary ou secondary, e qualquer outro valor lança um erro. No terminal, um botão primary é desenhado na cor de destaque, a menos que seja plain.
  • role: dismiss marca um botão de fechar, e qualquer outro valor lança um erro. Faça o fechamento no seu onPress. Em uma faixa que contém texto e uma fileira de botões, o aplicativo Desktop pode desenhar o primeiro botão dismiss da fileira como seu próprio controle de fechar. O terminal desenha o botão como faria sem role.

Um 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 um Button.
  • Nomear o botão: o label nomeia o botão e, por padrão, é o texto de seus children. Dê um key ou um label a 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

[!NOTE]

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: position com seus top, left, right e bottom, alignSelf, borderDimColor e hover
  • Text: size, mono, tabular e hover
  • Button: hotkey, plain, autoFocus, action e hover, 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 ignora variant e role.
  • 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, e rows em um Input
  • Svg: 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.

borderStyle O que o terminal desenha Borda superior
'single' Linhas finas com cantos retos ┌──┐
'double' Linhas duplas ╔══╗
'round' Linhas finas com cantos arredondados ╭──╮
'bold' Linhas grossas ┏━━┓
'singleDouble' Linhas finas em cima e embaixo, linhas duplas nas laterais ╓──╖
'doubleSingle' Linhas duplas em cima e embaixo, linhas finas nas laterais ╒══╕
'classic' Os caracteres ASCII +, - e | +--+
'arrow' Setas que apontam para dentro do Box ↘↓↓↙
'dashed' Linhas tracejadas com cantos em branco ╌╌
'quote' Uma barra, ▎, no lado esquerdo e células em branco nos outros três lados Em branco

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:

Passo Células na horizontal Células na vertical
'xs' 1 0
'sm' 1 0
'md' 2 1
'lg' 3 1
'xl' 4 2

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.

Prop Valores No terminal Na extensão do VS Code
size 'caption', 'footnote', 'body', 'heading' ou 'title' Ignorada: o terminal tem um único tamanho de texto Ignorada
weight 'regular', 'medium', 'semibold' ou 'bold' semibold e bold são desenhados como texto em negrito semibold e bold são desenhados como texto em negrito
mono true para pedir a fonte monoespaçada do aplicativo Ignorada: o terminal é sempre monoespaçado Ignorada, então o texto mantém a fonte própria da extensão
tabular true para pedir dígitos de largura igual, para que um número que é atualizado no lugar ou uma coluna de números permaneça alinhado Ignorada: os dígitos do terminal já têm uma célula de largura Ignorada

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 de Raster ou de bytes de Image não é desenhada.

Limite Valor
O tempo de execução próprio de um hook para um evento, sem contar o tempo dentro de next ou de uma chamada à API de mods que não seja $.clock.sleep 10 segundos, ou 50 milissegundos para um hook prompt.edit
O tempo de execução de um manipulador .catch 1 segundo
Todos os hooks session.end juntos O mesmo que o orçamento do hook SessionEnd, 1,5 segundo a menos que você o altere, contado a partir do momento em que os hooks SessionEnd das suas configurações terminam
Timeout de $.process.run 30 segundos por padrão, no máximo 10 minutos
stdout e stderr de $.process.run 4 MiB cada. isStdoutTruncated ou isStderrTruncated é true quando um deles foi cortado.
maxTokens de $.model.complete 1024 por padrão, até 64.000 ou o limite de saída do modelo
$.fs.read e $.fs.write 4 MiB para um arquivo
O corpo de uma requisição de $.http.fetch 4 MiB, contados em caracteres. Uma chamada com um corpo maior é rejeitada.
O corpo de uma resposta de $.http.fetch 4 MiB. text contém os primeiros 4 MiB e o restante não é lido. Quando o cabeçalho Content-Length declara mais, a chamada é rejeitada em vez disso, com um motivo que termina em is over the 4194304-byte limit, exceto quando a última requisição após quaisquer redirecionamentos usa o método HEAD. A isenção para HEAD requer o Claude Code v2.1.296 ou posterior.
Uma chamada de $.http.fetch, incluindo redirecionamentos e corpo 30 segundos
Redirecionamentos que uma chamada de $.http.fetch segue 5
O motivo de drop de um hook ou o motivo de deny de config.set 4.096 caracteres. O final de um motivo mais longo é cortado, e o drop ou deny ainda se aplica. O corte requer o Claude Code v2.1.292 ou posterior e, em versões anteriores, o hook falha em vez disso.
Texto em uma árvore Os primeiros 100.000 caracteres são desenhados
O language ou path de um Code, o value de uma opção de Select ou o module de um Client 10.000 caracteres. Se algum for mais longo, o hook ui.render que o retornou falha.
O href de um Link 2.048 caracteres. Se for mais longo, o hook ui.render que o retornou falha.
Profundidade de aninhamento de uma árvore 32 níveis abaixo do elemento raiz
Elementos e filhos de texto em uma árvore 20.000
Células de Raster em uma árvore, o columns de cada Raster multiplicado pelo seu rows 262.144
Bytes PNG ou RGBA de todas as Images em uma árvore 2 MiB
$.store 4 MiB de JSON no total
$.session.messages() As 4.096 entradas mais recentes
Redesenhos de $.ui.invalidate('ui.render') Limitados a 10 por segundo, ou 30 no terminal para o painel visível, a faixa expandida e a linha de dica abaixo do prompt. Chamadas que chegam antes disso são agrupadas.
$.ui.toast Exibido por 4 segundos, a menos que você passe { timeoutMs }. No renderizador clássico, um toast mais recente de um mod pode tomar o lugar do mais antigo que está sendo exibido ou aguardando para ser exibido.
Um painel aberto sem que o usuário tenha pedido Posicionado a partir de 144 colunas do terminal, 110 depois que o usuário o tiver aberto uma vez
Linhas de $.ui.place que um mod tem em uma conversa ao mesmo tempo 500. No limite, uma chamada com um novo id é resolvida como { isPlaced: false, reason: 'a plugin holds at most 500 placed rows' }.
Profundidade de aninhamento dos argumentos de uma chamada à API de mods 28.000 níveis. Além disso, a chamada é rejeitada com uma mensagem que termina em nesting deeper than 28000 levels is not supported. Requer o Claude Code v2.1.299 ou posterior.
Profundidade de aninhamento de um evento alterado passado para next, fora de hooks de gerador assíncrono como um em turn.step 28.000 níveis. Além disso, next é rejeitado com uma mensagem que termina em nesting deeper than 28000 levels is not supported. Requer o Claude Code v2.1.299 ou posterior.
Profundidade de aninhamento do valor de retorno de um hook, fora de ui.render, ui.resolve e hooks de gerador assíncrono 28.000 níveis. Além disso, o resultado do hook é recusado, e o aviso que o relata inclui nesting deeper than 28000 levels is not supported. Requer o Claude Code v2.1.299 ou posterior.
Escopos, como funções, blocos e loops, aninhados uns dentro dos outros em um arquivo de um módulo de hooks 2.000
Nomes de comandos, ferramentas, tipos de subagente e painéis, e o id de uma linha posicionada ou de um pano de fundo Letras, dígitos, _ e -, até 64 caracteres
Um teste do claude plugin test 5 segundos, a menos que o teste defina timeoutMs

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:

Nome Onde O que faz
CLAUDE_CODE_PLUGIN_DIRS Ambiente, ou env em ~/.claude/settings.json Diretórios de plugin a carregar como --plugin-dir faz, para aplicativos aos quais você não pode passar uma flag. Caminhos absolutos separados por :, ou ; no Windows.
CLAUDE_CODE_PLUGIN_DIR_WATCH Ambiente 1 faz com que uma sessão não interativa de longa duração recarregue os mods de --plugin-dir ao salvar
prependPlugins, appendPlugins Configurações gerenciadas. Configurações do usuário somente em uma máquina sem configurações gerenciadas, em uma sessão cuja credencial não é um /login Team ou Enterprise. Listas de ids de plugin, como acme-guard@acme-tools. Mods em prependPlugins são executados antes de todo mod que um usuário instala, e mods em appendPlugins são executados depois, na ordem listada. Consulte A ordem em que os mods são executados.
allowManagedModsOnly Configurações gerenciadas, como uma opção da guarda integrada Somente mods que contam como da sua organização, e mods integrados ao Claude Code, executam seus hooks. Os hooks de configuração dos usuários continuam em execução.
allowModsToOverrideDenyRules Configurações gerenciadas, como uma opção da guarda integrada Permite que um mod instalado por um usuário aprove uma chamada de ferramenta que uma regra deny recusa
allowManagedHooksOnly Configurações gerenciadas Bloqueia hooks e mods instalados que não são da sua organização. Consulte o que continua em execução.
disableAllHooks Qualquer arquivo de configurações Nas configurações gerenciadas, nenhum mod ou hook de um plugin instalado é executado. Nas suas próprias configurações, o que a sua organização gerencia continua em execução. Consulte disableAllHooks.
disableSideloadFlags Configurações gerenciadas Rejeita --plugin-dir e --plugin-url na inicialização
pluginConfigs Configurações do usuário ou gerenciadas Contém valores de userConfig para um mod, indexados pelo id do plugin, como acme-guard@acme-tools, ou pelo seu nome e @inline, como first-mod@inline, para um carregado com --plugin-dir

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 em uma sessão cuja credencial é um /login 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.

Comando O que faz
/plugin Mostra uma linha como 1 mod active · first-mod abaixo de suas abas quando um mod que não é integrado foi carregado
claude plugin validate <directory> Lê o manifesto e o módulo de hooks de um plugin e informa erros, os eventos que ele trata e as chamadas à API de mods que ele faz. --strict trata avisos como erros e --json imprime um relatório legível por máquina.
claude plugin test [directory] Executa todos os arquivos no diretório, ou no diretório atual quando nenhum é informado, cujo nome termina em .test.ts ou .test.tsx. Sai com status 1 quando um teste falha.
claude --plugin-dir <directory> Carrega um diretório de plugin para uma sessão e recarrega seu módulo de hooks quando você salva. Repita a flag para carregar vários.
/reload-plugins Recarrega os plugins quando você o executa