Pular para o conteúdo principal
Um mod pode desenhar sua própria interface no Claude Code e alterar partes da interface que o Claude Code já desenha. Cada lugar onde um mod pode desenhar é chamado de site de renderização, como um painel, a faixa acima do prompt ou o spinner. O Claude Code dispara o evento ui.render cada vez que está prestes a desenhar um site de renderização, e seu hook para esse evento retorna o que desenhar lá. Este mapa mostra onde um mod pode desenhar em uma sessão de terminal: Mapa de uma sessão de terminal Claude Code com renderização em tela cheia. Um mod pode adicionar um painel como uma barra lateral à direita, um toast no canto superior direito da transcrição, uma linha de log na transcrição, uma faixa acima do prompt e uma linha de status sob o prompt. Um mod pode redesenhar mensagens, linhas de chamada de ferramenta e o spinner. O prompt é do próprio Claude Code. Mapa de uma sessão de terminal Claude Code com renderização em tela cheia. Um mod pode adicionar um painel como uma barra lateral à direita, um toast no canto superior direito da transcrição, uma linha de log na transcrição, uma faixa acima do prompt e uma linha de status sob o prompt. Um mod pode redesenhar mensagens, linhas de chamada de ferramenta e o spinner. O prompt é do próprio Claude Code. Em um terminal mais estreito, o painel fica acima do prompt em vez de ao lado da transcrição. Crie seu primeiro mod antes de começar aqui. Comece com o exemplo trabalhado, que cria um painel com duas abas e um contador, depois leia a seção para cada parte que você deseja alterar.
Para procurar uma propriedade ou limite, consulte a referência.

Construir um painel com abas

Nesta seção você constrói um mod que adiciona um comando /hello-tabs e o comando abre um painel. Um painel é uma barra lateral ao lado da transcrição em um terminal fullscreen amplo, ou uma região enquadrada acima do prompt caso contrário. Este painel mostra duas abas, e a segunda aba tem um botão que adiciona um ao contador. A contagem ainda está lá depois que você reinicia o Claude Code. O mod finalizado se parece com isto. A gravação abre o painel, muda para a segunda aba, pressiona o botão algumas vezes e retorna à primeira aba:
As abas são dois botões em uma linha. O mod acompanha qual está ativo e desenha o conteúdo dessa aba sob a linha.
1

Criar o plugin

Um mod é um plugin com um manifesto, um hooks.json que aponta para seu código, e o arquivo de código. Criar um mod explica cada um. Crie um diretório chamado hello-tabs com diretórios .claude-plugin e hooks dentro dele, depois salve os dois primeiros arquivos.Salve o manifesto como hello-tabs/.claude-plugin/plugin.json:
hello-tabs/.claude-plugin/plugin.json
Nomeie seu ponto de entrada em hello-tabs/hooks/hooks.json:
hello-tabs/hooks/hooks.json
2

Escrever o código

Esta lista diz o que cada hook faz, na ordem em que aparecem no código:
  • Adiciona o comando /hello-tabs e carrega a contagem que uma sessão anterior salvou
  • Abre o painel quando você executa esse comando
  • Desenha o conteúdo do painel: a linha de abas e o corpo da aba aberta
Duas variáveis no nível do módulo, tab e count, mantêm o estado do painel.Salve isto como hello-tabs/hooks/register.js:
hello-tabs/hooks/register.js
Cada hook também faz algo que o código não deixa claro:
  • session.start também lê a contagem salva de $.store, um armazenamento de chave-valor que persiste entre sessões.
  • command.run apenas diz ao Claude Code que o painel existe. Abrir um painel não desenha nada por si só: o Claude Code então dispara ui.render para perguntar o que colocar nele.
  • ui.render retorna a árvore de elementos, uma Box que contém outras caixas, texto e botões, e a constrói novamente a partir de tab e count cada vez que é executada.
Pressionar um botão executa seu callback onPress, que altera uma variável e chama redraw. O Claude Code então executa o hook ui.render novamente, e o hook constrói uma nova árvore a partir dos novos valores. Cada desenho interativo usa esse ciclo de renderização: um callback altera o estado e o hook renderiza novamente a partir do novo estado.
3

Abrir o painel

Em seu shell, inicie o Claude Code com claude --plugin-dir ./hello-tabs. No prompt Claude Code, execute /hello-tabs. Um painel abre com 1: One e 2: Two na parte superior. Pressione 2, depois pressione a, o atalho de teclado para Add one, algumas vezes. A contagem sobe.
4

Verificar se a contagem foi salva

Pressione Esc para fechar o painel, depois saia da sessão. Em seu shell, inicie o Claude Code novamente com o mesmo comando claude --plugin-dir ./hello-tabs e no prompt Claude Code execute /hello-tabs. A contagem está onde você a deixou.Para limpar a contagem, faça o mod chamar $.store.delete('count'). Manter estado cobre quanto tempo cada tipo de valor dura.

Escolher onde desenhar

Para escolher o ponto de renderização em que um hook ui.render desenha, passe um filtro, chamado de matcher, como o segundo argumento para on. { component: 'Pane' } executa o hook apenas para painéis. No hook, e.component nomeia o ponto, e.surface diz qual app está desenhando, e e.props contém os dados do próprio ponto. Para um painel, e.requestId é o id com que você o abriu. O painel e a faixa ficam vazios até um mod preenchê-los. Selecione uma aba para ver o que cada um é e como desenhar nele:
Um painel é uma barra lateral ao lado da transcrição em um terminal fullscreen amplo, ou uma região enquadrada acima do prompt caso contrário. Com vários painéis abertos, cada um recebe uma aba que mostra seu título.Um painel aparece quando seu mod chama $.ui.open com um id que você escolhe, como em $.ui.open({ id: 'hello-tabs' }). Abrir um painel no momento certo cobre os outros campos e quando um painel espera por um terminal mais amplo.Para desenhar em seu painel, filtre em { component: 'Pane' } e verifique se e.requestId é seu id.
Um mod também pode colocar uma linha própria na transcrição.

Alterar o que o Claude Code já desenha

O Claude Code desenha a maior parte de sua interface por si só: mensagens, linhas de chamada de ferramenta, o spinner e muito mais. Cada uma dessas partes é um site de renderização também, então um mod pode restylar ou substituí-la. Para alterar uma, filtre seu hook ui.render em seu nome desta tabela: Pane, AskUserQuestion, Spinner, UserMessage, AssistantMessage e os pontos de chamada de ferramenta funcionam no terminal, no app Desktop e na extensão do VS Code. A tabela de pontos de renderização lista onde cada um dos outros é disparado. Em um site que o Claude Code já desenha, seu hook pode alterar um detalhe, substituir o desenho ou deixá-lo em paz. Selecione uma aba para ver cada um aplicado ao spinner. Os exemplos leem uma variável calls que outro hook conta, como no mod do tutorial.
Para manter o desenho do Claude Code e alterar uma parte dele, passe para next uma cópia do evento com props alteradas. Este hook altera o texto após a palavra do spinner:
O spinner mantém sua animação e sua palavra, e seu texto segue a palavra:
Nesses sites, next(e) retorna uma referência ao desenho do Claude Code, { type: 'engine', ref }, a menos que um mod executado depois do seu tenha retornado uma árvore própria. Para alterar o que está nesse desenho, passe para next uma cópia do evento com props diferentes, como faz a aba Change a detail. Você pode retornar a referência como está, ou colocá-la em uma Box ao lado de elementos seus:
Enquanto o Claude trabalha, o spinner anima como antes, e under the spinner aparece abaixo dele. O prompt de permissão não é um ponto de renderização, então um mod não pode alterar o que ele mostra. O diálogo de pergunta, AskUserQuestion, é um, então um mod pode alterar esse diálogo quando o Claude faz uma pergunta. Uma árvore para o diálogo precisa conter a referência exatamente uma vez, com seus elementos acima dela. Caso contrário, o Claude Code desenha seu próprio diálogo.

Abrir um painel no momento certo

Um painel aparece apenas quando seu mod o abre. Como e quando você o abre decide se ele toma o foco do teclado, quanto espaço ele pede e se aparece em um terminal estreito. Para abrir um painel, chame $.ui.open com um id que você escolhe. O id é o nome do painel: seu hook ui.render verifica, e você o passa novamente para fechar o painel. Se outro mod tiver um painel aberto com esse id, a chamada é rejeitada.
Para fechar o painel, chame $.ui.close com o id que você abriu com:
Além de id, $.ui.open leva estes campos opcionais: A extensão do VS Code ignora rows e columns e dimensiona o painel por conta própria. focus, closeOnEscape e holdToasts são opcionais e aceitam apenas true. Para deixar um de fora, omita-o. Passar false lança um erro como ui.open: focus is true or left out. Para definir um deles condicionalmente, adicione o campo apenas quando a condição se mantiver. Esta chamada solicita foco do teclado apenas quando items não está vazio:
Para deixar um comando abrir o painel enquanto o Claude está trabalhando, adicione immediate: true quando você registra o comando. Sem isso, um comando digitado durante um turno espera o turno terminar.

Reter toasts atrás de um diálogo

Passe holdToasts: true para $.ui.open quando o painel for um diálogo que o usuário responde e deixa, para que toasts não apareçam enquanto ele decide. No terminal, a retenção dura enquanto esse painel é o que está sendo exibido, e um toast disparado nesse tempo espera até a retenção terminar. O Claude Code retém os toasts de outros mods e suas próprias notificações de curta duração, assim como os que seu mod dispara com $.ui.toast. Deixe o campo de fora em um painel que permanece aberto, para que o usuário continue vendo-os.

Quando um painel espera por um terminal mais amplo

Um painel que seu mod abre sem ser solicitado não aparece em um terminal estreito, então não pode assumir uma tela pequena. Se aparece depende do que o abriu:
  • Aberto por algo que o usuário fez, como um comando que executou ou um botão que pressionou, o painel aparece em qualquer largura
  • Aberto por seu mod agindo por si só, como de um timer ou um hook turn.start, o painel aparece apenas em um terminal com pelo menos 144 colunas de largura. Depois que o usuário abriu esse painel uma vez por si só, 110 colunas é suficiente.
Quando o painel aparece, $.ui.open resolve para { isPlaced: true }. Quando o painel está esperando, isPlaced é false e reason é uma string que diz por quê. Um painel esperando aparece quando o usuário o abre ou amplia o terminal. Para dizer que algo está disponível sem abrir um painel, chame $.ui.toast('Your message'), que mostra uma notificação toast.

Desenhar na extensão do VS Code

Na extensão do VS Code, o que um mod desenha aparece no painel de chat com a versão 2.1.299 ou posterior da extensão. Uma sessão que não busca feature flags, como uma no Amazon Bedrock, precisa da versão 2.1.304 ou posterior. Em um hook ui.render para o painel, e.surface é vscode. Para verificar quais pontos e elementos o painel desenha, e quais props ele ignora, consulte as tabelas de pontos de renderização e de elementos. Para fazer um mod funcionar no painel assim como no terminal, leve em conta estas diferenças:
  • Painéis: em um painel de chat com 800 pixels ou mais de largura, os painéis se encaixam ao lado da conversa, e.props.placement é 'dock' e e.viewport.isFullscreen é true. Em um painel de chat mais estreito, os painéis são desenhados acima da caixa do prompt, placement é 'inline' e um painel mostra 12 linhas antes de rolar.
  • Toasts e linhas de status: ficam em uma única pilha diretamente acima da caixa do prompt, junto com os painéis quando o painel de chat é estreito, com uma linha de status por mod. A pilha fica oculta enquanto uma solicitação de permissão ou um diálogo é exibido.
  • Rótulos: o painel de chat enquadra o que um mod desenha ou reescreve e o rotula com o nome do plugin, como em From the token-chart plugin ou Edited by the token-chart plugin.
  • Teclado: os botões não têm teclas de atalho, então o usuário clica em um botão ou pressiona Enter nele quando ele tem o foco.
  • Foco do teclado: o painel de chat concede a solicitação focus: true de um painel apenas quando o painel de chat tem o foco, o Claude está ocioso sem nenhuma pergunta aguardando e a caixa do prompt está vazia.
  • O diálogo de pergunta: em AskUserQuestion, o painel de chat mantém seu próprio cartão de pergunta e desenha seus elementos acima dele. As props que você passa para next não alteram o cartão.
  • Sugestões de prompt: $.prompt.suggest resolve com isShown: false e não mostra nada, porque o painel de chat reserva o texto de sugestão esmaecido da caixa do prompt para as próprias sugestões do Claude.
  • Limites de texto: o painel de chat corta uma linha de status em 200 caracteres ou duas linhas, e um toast em 500 caracteres.

Colocar uma linha na transcrição

Uma linha é uma linha que seu mod adiciona à transcrição no terminal, após a mensagem mais recente. Ela permanece nesse lugar conforme a conversa avança, e o Claude não a vê. $.ui.place requer o Claude Code v2.1.314 ou posterior.
1

Colocar a linha

Chame $.ui.place com um id. O id é um nome que você inventa para a linha, como build-status. Ele pode ter de 1 a 64 letras, dígitos, _ ou -, e cada linha que seu mod tem na transcrição precisa do seu próprio.
2

Desenhar a linha

Desenhe a linha no ponto de renderização Placed.
Este exemplo adiciona um comando /build-status. Quando o usuário executa o comando, o mod adiciona uma linha que mostra Build: passing. O texto é fixo para manter o exemplo curto, então um mod real desenharia seu próprio resultado:
Para experimentar o exemplo, coloque este código em um mod. Em uma sessão no terminal, execute /build-status no prompt do Claude Code. Build: passing aparece como uma linha no final da transcrição. A chamada nem sempre mostra uma linha, e uma linha pode desaparecer depois, então trate estes casos no seu mod:
  • O resultado: { isPlaced: true, requestId } quando o terminal desenha a linha. Caso contrário, isPlaced é false e reason diz por quê, como em no attached surface draws placed rows yet. Um dos motivos é o limite de linhas que um mod pode ter ao mesmo tempo.
  • Uma segunda chamada com o mesmo id: enquanto a primeira linha ainda está na transcrição, a chamada não adiciona nenhuma linha e resolve com o requestId dessa linha. Para alterar o que a linha mostra, redesenhe a linha.
  • Quando a linha desaparece: quando a conversa termina, quando o usuário volta para antes da linha ou, fora da renderização em tela cheia, quando a conversa é compactada. --resume não traz a linha de volta. Para mostrar a linha novamente, chame $.ui.place de novo.

Colocar um plano de fundo atrás da conversa

$.theme.set e $.theme.clear substituem $.ui.backdrop, que o Claude Code v2.1.319 removeu. Altere $.ui.backdrop({ id: 'your-backdrop' }) para uma chamada $.theme.set como a do exemplo desta seção, e $.ui.backdrop(undefined) para $.theme.clear(), que remove o plano de fundo de qualquer mod.
Para colocar um plano de fundo atrás da conversa no app Desktop ou no app móvel, chame $.theme.set com um backdrop e, em seguida, desenhe o plano de fundo no ponto de renderização Backdrop. Para remover o plano de fundo, chame $.theme.clear(). O terminal não desenha plano de fundo. $.theme.set e $.theme.clear requerem o Claude Code v2.1.319 ou posterior. Este exemplo requer o Claude Code v2.1.323 ou posterior, então verifique sua versão primeiro. O mod define um plano de fundo quando a sessão começa, desenha o plano de fundo e adiciona um comando /plain que remove o plano de fundo:
Antes da v2.1.323, escreva id no lugar de scene na chamada $.theme.set e em e.props, e mova overrideColorScheme para dentro de backdrop como colorScheme.
Para experimentar o exemplo, coloque este código em um mod e inicie uma sessão no app Desktop ou no app móvel. Para remover o plano de fundo, execute /plain no prompt do Claude Code. A transcrição mostra the theme is cleared após o nome do mod, como em night-sky: the theme is cleared para um mod chamado night-sky. Verifique o que backdrop aceita, o que o resultado da chamada informa e o que outros mods podem alterar:
  • Os campos de backdrop: scene é um nome que você escolhe para um plano de fundo que seu hook desenha. Para os outros campos e overrideColorScheme, consulte os tipos para o seu build.
  • Se o plano de fundo é desenhado: $.theme.set resolve com isDrawn: true quando um app Desktop ou móvel conectado à sessão informa que desenha planos de fundo. Caso contrário, isDrawn é false e reason diz por quê.
  • Um tema para cada sessão: um mod que chama $.theme.set substitui o plano de fundo e as cores da sessão, e um mod que chama $.theme.clear() os remove, independentemente de qual mod os definiu. Chame $.theme.clear() apenas quando o usuário pedir.

Alterar as cores do app Desktop

Para alterar as cores da aba Code do app Desktop com um mod, peça um ao Claude ou escreva um você mesmo. As duas formas requerem o Claude Code v2.1.324 ou posterior na aba Code, então verifique a versão ali primeiro. O Claude Code no terminal mantém suas próprias cores.

Pedir ao Claude um mod de cores

1

Descrever as cores

Inicie uma sessão local na aba Code e diga ao Claude quais cores você deseja. Por exemplo, digite make a mod that makes the app cream in light mode and dark brown in dark mode. O Claude escreve os arquivos do mod.
2

Aprovar o mod

Responda às perguntas que o Claude Code faz sobre os arquivos do mod e o hot reloading. Para saber o que cada resposta faz, consulte Pedir um mod ao Claude.
3

Verificar as cores

A aba Code muda de cor quando o mod é carregado. Para ajustar uma cor, diga ao Claude o que alterar. Se nada mudar, consulte Corrigir cores de mod ausentes.

Escrever um mod de cores você mesmo

makeColors é uma função que constrói um tema a partir de algumas cores hex. Estas etapas criam um mod chamado paper que a utiliza.
1

Pedir ao Claude para copiar makeColors

Inicie uma sessão local na aba Code e digite copy make-colors.js and make-colors.d.ts from your plugin-authoring skill into ~/.claude/skills/paper/hooks/. Verifique se os dois arquivos estão nesse diretório.
2

Salvar o manifesto e o hooks.json

A partir de Escrever um mod você mesmo, salve .claude-plugin/plugin.json e hooks/hooks.json em ~/.claude/skills/paper/ e altere first-mod para paper nos dois arquivos. Um mod em ~/.claude/skills/ é carregado quando você inicia uma sessão.
3

Escrever o código

Salve este arquivo como ~/.claude/skills/paper/hooks/register.js. Quando uma sessão começa, o código chama $.theme.set com as cores para o modo claro e o modo escuro:
Para usar suas próprias cores, substitua os valores hex por outras cores hex de seis dígitos.
4

Verificar as cores

Inicie uma nova sessão local na aba Code. Com os valores do exemplo, o plano de fundo fica creme no modo claro e marrom-escuro no modo escuro. Se nada mudar, consulte Corrigir cores de mod ausentes.

Corrigir cores de mod ausentes no app Desktop

Se você usa um provedor terceirizado em vez de uma conta Claude no Claude Desktop v5.11492.5 ou anterior, a aba Code mantém suas próprias cores, então ignore estas verificações. Caso contrário, se as cores de um mod não aparecerem na aba Code, ou se desaparecerem, verifique estas causas:
  • Versão antiga: atualize o app Desktop, reinicie-o e inicie uma nova sessão local na aba Code. Se o Claude escreveu o mod, peça-o novamente ali.
  • Mod não carregado: se o Claude escreveu o mod, veja quando ele é carregado em Pedir um mod ao Claude. Se você o escreveu, compare seus arquivos e os caminhos deles com Escrever um mod de cores você mesmo.
  • Tema recusado: peça ao Claude para executar a chamada makeColors do mod. Se a chamada lançar um erro, ou se a lista problems dela tiver uma entrada que comece com Desktop won't paint this theme, peça ao Claude para corrigir o tema. Se você instalou o mod, envie o que o Claude encontrar para o autor dele.
  • Outra chamada $.theme: quando qualquer mod na sessão chama $.theme.set ou $.theme.clear(), as cores e o plano de fundo de uma chamada anterior desaparecem. No seu próprio mod, passe colors e backdrop na mesma chamada $.theme.set. Use um mod de cada vez que defina um tema.

Remover cores de mod do app Desktop

Para remover as cores de um mod da aba Code, desative o mod primeiro. Um mod que ainda está ativado pode definir suas cores novamente.
1

Desativar o mod

2

Iniciar uma nova sessão

Inicie uma nova sessão local na aba Code.
3

Remover cores que permanecem

Se as cores ainda estiverem lá, abra Settings a partir da aba Code e pesquise ali por code appearance. Abra o resultado e selecione Remove colors.

Construir uma árvore a partir de elementos

O que um hook ui.render retorna é uma árvore de elementos: uma descrição do que desenhar, feita de caixas, texto e controles aninhados um dentro do outro. Você descreve o desenho, e o Claude Code o renderiza no app que o usuário tiver aberto: o terminal, o app Desktop ou a extensão do VS Code. Para obter os elementos, chame $.ui.resolve(e) em seu hook, como em const { Box, Text, Button } = $.ui.resolve(e). Cada elemento é uma função. Você passa propriedades para ela, e coloca os elementos e strings que vão dentro dela em children. Selecione uma aba para ver cada um dos elementos mais comuns e como o terminal o desenha:
Text desenha uma string, com estilo opcional como bold e color:
A galeria de interface tem exemplos e capturas de tela da maioria dos elementos. Esta tabela lista os principais elementos: Se seu módulo é um arquivo .tsx ou .jsx, você pode escrever a árvore como JSX. Desestruture os elementos de $.ui.resolve(e) primeiro. Se seu desenho não aparecer, verifique se a árvore tem uma prop que um elemento não leva ou um filho onde nenhum vai. Um hook que retorna uma árvore assim falha, e uma linha hook skipped nomeia seu mod e a regra que a árvore violou. Para um Text em um painel com uma prop chamada bogusProp, essa linha diz:
No app Desktop e na extensão do VS Code, um Link é desenhado como texto simples, a menos que seu href atenda a estes requisitos:
  • Esquema e host: uma URL https:, ou uma URL http://localhost como http://localhost:3000
  • Sem @: escreva um @ no caminho ou na query como %40
  • Grafia: o que new URL(href).href retorna, exceto por uma / ausente após o host. Isso exclui um host em maiúsculas, um espaço e :443 em uma URL https:.
No terminal, esses requisitos não se aplicam.

Quando um Client falha

No terminal, quando o arquivo que um Client executa falha, uma linha esmaecida como my-mod: Client client/spinner.js: boom ocupa o lugar do Client, e o restante do seu desenho continua aparecendo. Se seu mod trata ui.fault, o Claude Code então desenha o site novamente.

Desenhar uma grade de células coloridas

Para um mapa de calor, um sparkline ou um tabuleiro de jogo no terminal, desenhe um Raster e não uma Box para cada célula. Um Raster leva uma key, seu tamanho em columns e rows, e cells, uma string base64 que empacota cada célula. Cada célula é três números: o ponto de código do caractere, sua cor e sua cor de fundo. Uma cor é um valor RGB de 24 bits em hexadecimal, como 0xc62828 para um vermelho. O valor 0x01000000, um acima desse intervalo, significa o padrão do terminal. Os apps que não são o terminal não têm Raster, então verifique e.surface e desenhe texto lá. Este corpo de painel desenha um mapa de calor de três por dois:
No terminal, o painel mostra a grade: Um painel no terminal que contém uma pequena grade de blocos coloridos, duas linhas de três. A linha superior é verde, âmbar e vermelho. A linha inferior é verde, verde e âmbar. O array rows é a parte que você alteraria, e cellsOf a transforma na string empacotada. O hook desenha apenas em um painel cujo id é heat, então abra um com $.ui.open({ id: 'heat' }) de um comando, como o exemplo hello-tabs abre seu painel. Cada caractere tem que ser uma célula de largura. Para animar um Raster que já está na tela, chame $.ui.blit com o id do painel como requestId, a key do Raster, o mesmo tamanho e novas células. Para este exemplo, é $.ui.blit({ requestId: 'heat', key: 'grid', columns: 3, rows: 2, cells: cellsOf(newRows) }). Ele repinta apenas esse elemento sem executar seu hook ui.render novamente.

Responder a pressionamentos e digitação

Quando o usuário pressiona um botão, digita em um campo ou escolhe de uma lista que seu mod desenhou, o Claude Code chama o callback desse controle, que é executado em seu módulo. Cada controle leva seus próprios callbacks:
  • Button: leva onPress(e), onde e.surface é o app de onde veio o pressionamento
  • Input: leva onSubmit(value) e onInput(value)
  • Select: leva onSelect(value) com suas escolhas em options, uma lista de pelo menos uma escolha com valores únicos, como [{ value: 'sm', label: 'Small' }, { value: 'lg', label: 'Large' }]

Quais controles precisam de uma key

Dê a cada Input e Select uma prop key, como key: 'size'. Um Button pode ficar sem key quando tem uma prop label ou um único filho de string. Sua key é então o valor de label ou essa string. Testes e outros mods identificam um controle por sua key:
  • Testes: um teste pressiona ou digita em um controle por sua key.
  • Outros mods: o Claude Code dispara ui.press, ui.input ou ui.select com a key do controle em e.element antes de executar o callback do controle. O hook de outro mod também pode ser executado para esse evento. Esse hook vê o que o usuário digitou em seu Input e pode alterar esse texto ou impedir que seu callback seja executado. A API de mods não dá a esse mod nenhum método para pressionar seus botões.
Se uma mensagem disser needs a key ou is drawn twice, encontre a causa por essa mensagem.

Foco do teclado e atalhos de teclado

Seu mod nunca lê o teclado por si só. O usuário pressiona uma tecla, o Claude Code decide qual de seus controles é para, e o callback desse controle é executado. Além de um atalho de teclado de dígito na faixa ou um vínculo de action, isso acontece apenas enquanto seu painel ou faixa tem foco do teclado. O resto do tempo, as teclas vão para o prompt. Na extensão do VS Code, os botões não têm atalhos de teclado: o usuário clica em um botão ou pressiona Enter nele, e digita nos campos.

Como um painel obtém foco do teclado

Um painel obtém foco do teclado quando:
  • Seu mod o abre com focus: true de um comando ou um pressionamento
  • O usuário pressiona Ctrl+X depois Tab
  • O usuário clica nele, o que no terminal requer renderização em tela cheia
O Claude Code concede focus: true apenas enquanto o prompt está vazio e nada mais tem foco do teclado. Um painel que abre enquanto o usuário está digitando não toma seus pressionamentos de tecla.

O que cada tecla faz

Esta tabela lista o que uma tecla faz enquanto seu painel ou faixa tem foco do teclado: Um mod não pode vincular Tab ou as setas para nada mais, então um jogo direciona com w, a, s e d.

Definir um atalho de teclado e o primeiro foco

  • hotkey: para deixar o usuário pressionar um Button com uma tecla, dê a ele um hotkey de um dígito ou uma letra minúscula, como em hotkey: 'a'
  • autoFocus: para escolher qual controle tem o foco quando o painel abre, adicione autoFocus: true a ele. Na extensão do VS Code, autoFocus não faz nada: o controle é desenhado como se você o tivesse omitido, e você não precisa alterar nada. A prop aceita apenas true, então omita-a nos outros controles.
Como um atalho de teclado mostra depende do botão e do app: No terminal, nomeie a tecla no rótulo de um botão entre colchetes, ou use plain: true, para que o usuário possa ver o que pressionar. A referência de elementos tem as outras regras de Button: action, atalhos de teclado de dígito na faixa e dois botões em um atalho de teclado.

Quando o usuário recolhe a faixa

No terminal, enquanto um mod desenha na faixa, o usuário pode recolher a faixa para uma linha para tirá-la do caminho:
  • Clicar em [-]: enquanto a faixa está expandida, o Claude Code desenha essa marca na extremidade direita de sua primeira linha. Na renderização em tela cheia, o usuário clica nela para recolher a faixa.
  • Pressionar Ctrl+X depois Ctrl+A: isso funciona quer o prompt, a faixa ou um painel tenha foco do teclado. O usuário pode vincular outras teclas a isso por meio da ação abovePrompt:toggle.
Uma faixa recolhida oculta tudo o que os mods desenham nela e mostra uma linha fraca em seu lugar, que nomeia as teclas que a expandem conforme o usuário as tem vinculadas:
As mesmas teclas, ou na renderização em tela cheia um clique na linha, expandem a faixa novamente. Até lá, nada pressiona um botão nela: nenhum atalho de teclado, nenhum dígito digitado em um prompt vazio e nenhum atalho de teclado para a action de um botão. Se a faixa tiver foco do teclado quando o usuário a recolher, o foco retorna para o prompt, e Ctrl+X depois Tab pula a faixa enquanto ela está recolhida. A faixa permanece recolhida até que o usuário a expanda, mesmo após /clear, e é expandida novamente na próxima vez que o Claude Code iniciar. Seu mod não pode expandi-la. Não faça da faixa o único lugar em que seu mod mostra algo que o usuário precisa responder. Para mostrar isso em outro lugar apenas enquanto a faixa está recolhida, leia e.props.isCollapsed em seu hook ui.render, que continua sendo executado. isCollapsed requer o Claude Code v2.1.321 ou posterior.

Tomar entrada digitada e desenhar uma linha para cada item

Muitos painéis são um campo de texto com uma lista sob ele. O exemplo nesta seção é um painel de notas: você digita uma nota e pressiona Enter para adicioná-la, e cada nota tem um botão x que a deleta. Com duas notas adicionadas, o terminal desenha o painel desta forma:
O ✕ na borda superior é a marca própria do Claude Code para fechar o painel. O exemplo usa estas técnicas:
  • Tomar entrada digitada: um Input chama onSubmit(value) com o texto do campo quando o usuário pressiona Enter, e onInput(value) em cada mudança
  • Desenhar uma lista: mapeie seus dados para uma linha cada, e dê a cada botão de linha sua própria key
Este hook desenha o conteúdo do painel:
Para tentar o painel:
  • Adicionar uma nota: digite uma linha e pressione Enter. A linha aparece como uma nova linha e o campo esvazia.
  • Deletar uma nota: pressione Tab até o botão x da nota ter o foco, depois pressione Enter. O x é o rótulo do botão e não um atalho de teclado, então digitar a letra não o pressiona.
Cada mudança segue o mesmo ciclo de renderização que hello-tabs: o callback altera notes, chama redraw e salva a lista em $.store. Se seu hook desenhar o painel novamente enquanto o usuário está digitando uma nota, o campo mantém o texto dele desde que o hook passe o mesmo value a cada vez. Para substituir o texto dele pelo seu, passe um value diferente. O exemplo salva as notas e não as carrega. Para trazê-las de volta na próxima sessão, leia-as em um hook session.start, da forma que hello-tabs lê count. Estas propriedades compõem a linha do campo, Note: Type a note and press Enter ⏎ add: Enviar um Input não inicia um turno a menos que seu callback chame $.prompt.submit.

Redesenhar um site

Um desenho é um instantâneo: mostra o que seu hook ui.render retornou a última vez que o hook foi executado. Para mostrar algo novo, o hook tem que ser executado novamente. O Claude Code o executa novamente para algumas mudanças, e seu mod pede o resto.

Quando o Claude Code redesenha sem ser solicitado

O Claude Code executa seu hook ui.render novamente quando as props do site mudam ou a largura do terminal muda. Quando um Client no site falha e seu mod trata ui.fault, o Claude Code executa o hook mais uma vez depois que seus hooks ui.fault retornam, para que seu hook ui.render possa deixar o Client de fora. Ele não executa o hook em um timer, e não pode dizer quando uma variável em seu módulo muda.

Redesenhar quando seus dados mudam

Para ter seus sites desenhados novamente após suas próprias mudanças de dados, chame $.ui.invalidate('ui.render'). Este painel conta pressionamentos. O callback do botão altera count, depois pede um redesenho:
Cada pressionamento aumenta o número no painel. O exemplo hello-tabs envolve a mesma chamada em sua função redraw. Um valor que você mantém em $.state não precisa da chamada, porque escrever o valor redesenha os sites que o leem.

Redesenhar em um timer

Para manter um relógio, uma contagem regressiva ou um valor de fora da sessão atual, redesenhe em um cronograma. Inicie um timer no hook session.start do módulo. Se o módulo já tiver um, como hello-tabs tem, adicione a linha $.clock.every a ele:
O Claude Code agora executa seu hook ui.render uma vez por segundo. O timer para depois que o módulo recarrega, e a nova instância do módulo inicia o seu próprio.

Com que frequência um site pode redesenhar

O Claude Code limita os redesenhos de um site, então seu mod pode chamar $.ui.invalidate com a frequência que seus dados mudam. Para saber com que frequência cada site pode redesenhar, consulte a tabela de limites. Chamadas que vêm mais rápido que o limite são combinadas em um redesenho. Esse redesenho executa seu hook uma vez, e o hook lê seus dados como estão naquele momento, então o valor mais recente é mostrado e os valores intermediários não. Uma animação não pode ser executada mais rápido que o limite.

Manter estado

O lugar onde um mod mantém um valor decide quanto tempo o valor dura: até o módulo recarregar, até a sessão terminar ou de uma sessão para a próxima. Escolha por quanto tempo o valor tem que durar: $.store.get(key) resolve para o valor ou undefined, e $.store.set(key, value) leva qualquer valor JSON.

Manter um valor em $.state

$.state mantém valores pela duração de uma sessão, e redesenha para você. É estado reativo: um hook ui.render que lê um valor se inscreve nele, então o Claude Code redesenha esse site cada vez que você escreve o valor, e você não chama $.ui.invalidate. Um valor em $.state também sobrevive a um recarregamento do módulo, o que uma variável não faz. Para configurá-lo, declare seus valores, aponte seu manifesto para a declaração, depois defina e use cada valor. Os exemplos movem o count de hello-tabs para $.state.

Declarar os valores

Declare os valores em um arquivo de declaração de tipos. A chave externa é o nome do seu plugin, e cada entrada sob ela é um valor e seu tipo. Salve isto como hello-tabs/types/index.d.ts:
hello-tabs/types/index.d.ts

Apontar o manifesto para a declaração

Para deixar claude plugin validate verificar seu código contra esse arquivo, adicione um campo types ao manifesto com seu caminho:
hello-tabs/.claude-plugin/plugin.json

Definir, ler e escrever um valor

Em seu módulo, defina cada valor com um padrão, leia-o enquanto desenha e escreva-o de um callback. atom nomeia um valor e seu padrão, read o retorna e update o escreve. Os três ajudantes chamam $.state.get e $.state.set para você:
Porque o hook ui.render leu count, o Claude Code executa o hook novamente cada vez que o botão o escreve. Estas regras se aplicam ao código:
  • Escreva plugin e key como strings literais: claude plugin validate as lê de sua fonte
  • Mantenha o resultado de cada chamada atom em uma const: se você declarar count com let, a validação falha com takes a source the scan can read
  • Declare cada valor no arquivo de declaração de tipos: caso contrário a validação falha com hello-tabs.count is not declared
  • Escreva de um callback ou hook de outro evento: um hook ui.render pode ler estado e não pode escrevê-lo, então escreva de onPress, onSubmit ou um hook para outro evento

Alterar hello-tabs para usar $.state

Para mover count em hello-tabs para $.state, altere cada linha que o usa:
  • No topo do módulo: adicione a linha import e substitua let count = 0 pela linha atom
  • No hook ui.render: adicione a linha read antes de tabButton e desenhe 'Count: ' + n no Text
  • No botão Add one: substitua onPress pelo da Salvar de mais de uma sessão, que salva a contagem bem como escreve-a
  • No hook session.start: substitua as duas linhas que leem saved pela chamada loadCount de Carregar um valor salvo novamente após /clear
Mantenha redraw para os botões de aba, porque tab ainda é uma variável.

Carregar um valor salvo novamente após /clear

Se seu mod copia um valor salvo de $.store para $.state em session.start, tem que copiá-lo novamente após /clear, /resume ou /branch. Esses comandos redefinem cada valor $.state para seu padrão, e session.start não dispara novamente. classic.SessionStart dispara, sim, após cada um deles, com e.source definido como clear, resume ou fork, então copie o valor novamente em um hook nele. Caso contrário seu desenho mostra o padrão, e um callback que salva o valor $.state escreve o padrão sobre o que você armazenou. Este código carrega count de ambos os hooks. Ele se baseia na versão $.state de hello-tabs, onde count é um atom e update é importado. Coloque loadCount acima de register e adicione a chamada loadCount ao hook session.start que você já tem. classic.SessionStart também dispara na inicialização e após compactação, que não redefine $.state, então o filtro em source mantém o hook aos três resets:
Com ambos os hooks em vigor, o painel mostra a contagem salva após /clear e não 0, e o próximo pressionamento de Add one adiciona à contagem salva. loadCount escreve o valor armazenado sobre o em $.state, e session.start dispara novamente cada vez que o módulo recarrega. Para manter o armazenamento de ficar para trás, salve em cada mudança, como o botão Add one faz. Para verificar o recarregamento sem uma sessão, teste o desenho após /clear.

Salvar de mais de uma sessão

Cada sessão em sua máquina que executa seu mod compartilha um $.store. Um get seguido por um set não é atômico. Quando duas sessões cada uma lê um valor, o altera e o escreve de volta, elas correm, e a segunda escrita substitui a primeira. Para tornar isso menos provável:
  • Dê a cada item sua própria chave: um set altera apenas sua própria chave, então sessões que escrevem chaves diferentes não sobrescrevem uma à outra
  • Leia novamente logo antes de escrever: para um valor que várias sessões alteram, get a chave no callback e construa o novo valor a partir disso, não de uma cópia que você carregou em session.start. Outra escrita de sessão ainda é perdida se cair entre seu get e seu set.
Este botão adiciona um ao que o armazenamento contém agora, depois atualiza o desenho:
Se uma segunda sessão pressionou seu próprio botão três vezes desde que esta sessão começou, este pressionamento mostra e salva uma contagem que inclui esses três.

Próximos passos