Usuários do Claude Code agora podem alterar a interface e o comportamento do assistente com funções em JavaScript ou TypeScript empacotadas como plug-ins. A Anthropic lançou as modificações em 1º de outubro, com suporte na CLI e na aba Code do Claude Desktop. Desenvolvedores podem adicionar à conversa um indicador de uso do contexto.

Segundo a Anthropic, as modificações são executadas com as permissões da máquina do usuário e não ficam em uma sandbox. Uma modificação também pode ler dados da sessão ou fazer chamadas a modelos. Examine o código e quem o publicou antes de instalá-la.

Este guia é para desenvolvedores que já usam o Claude Code e querem fazer uma pequena personalização visível. A tarefa é criar um indicador de uso da janela de contexto, examinar o plug-in resultante e decidir se vale a pena mantê-lo. As instruções se baseiam na documentação consultada em 2 de outubro para o Claude Code v2.1.287 e versões posteriores. A BIG CHANGE não executou este procedimento nem testou o código gerado de forma independente.

A grande mudança

  • O que mudou: as modificações do Claude Code adicionam funções que podem alterar eventos e desenhar elementos na interface do assistente, distribuídas pelo sistema de plug-ins já existente.
  • Por que isso importa: desenvolvedores podem integrar à sessão um indicador ou controle de fluxo de trabalho, mas o código recebe acesso à máquina e à conversa.
  • O que observar: se as chamadas e o comportamento da modificação correspondem ao objetivo, quais controles organizacionais se aplicam e se houve mudanças na API entre versões do Claude Code.

Confira a versão, a conta e o espaço de trabalho

Execute claude --version em um terminal. A documentação atual sobre modificações exige a versão v2.1.287 ou posterior e informa que elas ficam ativadas por padrão. As configurações anteriores de variáveis de ambiente para acesso antecipado não controlam esta versão.

Você precisa ter acesso ao Claude Code e a um espaço de trabalho que tenha marcado como confiável. A documentação de configuração lista contas Pro, Max, Team, Enterprise e Console, além de provedores de API de terceiros compatíveis. O plano gratuito do chat Claude não inclui o Claude Code. As configurações de uma organização podem impedir o carregamento de modificações criadas pelos usuários.

Use uma sessão interativa de terminal. A CLI e as sessões compatíveis do Desktop exibem as interfaces das modificações. Ganchos também são executados no painel de chat do VS Code e em sessões sem interface, onde os desenhos não aparecem. As sessões do Desktop no WSL não são compatíveis com plug-ins.

Crie e examine o indicador

O tutorial de 1º de outubro da Anthropic documenta o Token Weather, um indicador que lê o uso do contexto após cada turno. A porcentagem se baseia no contexto usado na última resposta e na janela de contexto do modelo. É um indicador de uso, não uma medida documentada da qualidade das respostas.

  1. Inicie claude no espaço de trabalho confiável. Peça que ele crie uma modificação que mostre a porcentagem do contexto, os tokens usados e o tamanho da janela de contexto acima do prompt, atualizando-se após cada turno concluído do agente principal. Solicite a API de uso da sessão documentada e uma implementação apenas visual, sem acesso a arquivos, execução de processos, solicitações de rede nem chamadas a modelos. Esta é nossa especificação mais restrita para o caminho documentado de criação; o pedido, por si só, não impõe essas restrições.
  2. Examine os arquivos criados pelo Claude. O manual de criação instala o plug-in no diretório da sessão, dentro de ~/.claude/dev-mods/. Inspecione o manifesto, a configuração dos ganchos e o código. O Claude Code perguntará se você quer ativar o recarregamento a quente; se aceitar, as modificações desta sessão e as revisões posteriores serão executadas.
  3. Antes de ativá-la, execute claude plugin validate e acrescente no terminal o caminho real do diretório do plug-in. Leia os ganchos de evento e as chamadas de API indicados. O comportamento previsto exige a leitura do uso, o estado e a renderização. Investigue também qualquer acesso a arquivos, variáveis de ambiente, processos, rede ou modelos, e examine no código as alterações feitas aos eventos. Uma validação bem-sucedida indica compatibilidade com o carregador, não uma garantia de segurança.
  4. Depois de aprovar uma implementação já examinada, execute /plugin e confira a aba Installed para verificar se a modificação aparece. Faça uma solicitação comum e confira se o indicador se atualiza após o turno. O sinal de conclusão é um plug-in carregado com valores de uso visíveis que se atualizam; apenas gerar um arquivo não demonstra que ele funciona.

Estas etapas não garantem que o Claude gere a implementação pretendida na primeira tentativa. A implementação completa do Token Weather e o exemplo de teste servem de referência para comparar o código gerado. O tutorial diz que uma leitura normal do uso da sessão é gratuita; solicitar um detalhamento pode enviar uma solicitação de contagem de tokens. Pedir ao Claude que escreva ou revise a modificação ainda consome o uso normal do Claude Code.

Mantenha o código e as permissões em evidência

Uma modificação criada na sessão é temporária. O manual de criação diz que, para mantê-la, copie o diretório para um local próprio e inicie as sessões com claude --plugin-dir seguido desse caminho. Cada carregamento grava declarações específicas da versão em .claude-plugin/types/; confira-as ao atualizar, pois a API pode mudar.

O manual de administração da Anthropic explica uma limitação que as regras de permissão de ferramentas podem ocultar. O mecanismo de segurança integrado é carregado para usuários Team ou Enterprise ou em máquinas com configurações gerenciadas. Na configuração padrão, regras de bloqueio têm prioridade sobre modificações de usuário que aprovam chamadas de ferramentas do Claude. Essas regras não restringem as próprias chamadas de API de arquivos ou processos feitas pela modificação. Administradores podem bloquear modificações instaladas por usuários ou aplicar uma modificação de política às chamadas delas.

A investigação da Pluto Security de 22 de setembro relatou acesso a credenciais, falsificação da interface e alteração remota de código em testes da implementação anterior ao lançamento. A Pluto vende software de segurança para essas extensões, e seu relatório é explicitamente anterior à disponibilidade geral. Ele é uma referência útil para examinar o código-fonte de um plug-in e suas dependências baixadas; os achados específicos não demonstram o comportamento da v2.1.287. A documentação atual da Anthropic detalha as permissões da versão lançada.

Desative uma modificação pelos controles do plug-in. --safe-mode exclui, em uma sessão, as modificações instaladas e outras personalizações.

Uso e custos

Os manuais de lançamento e de modificações da Anthropic não especificam uma cobrança separada para as modificações. A documentação de custos do Claude Code informa que o uso por assinatura consome a franquia do plano, enquanto o uso pelo Console e por provedores em nuvem é cobrado por tokens. Uma modificação que chama um modelo pode consumir essa franquia ou gerar cobrança. Confira /usage e a interface de cobrança correspondente à forma como você entrou; uma porcentagem do contexto não é uma fatura nem um limite de gastos.

Registre a versão do Claude Code junto com o plug-in examinado. Aprovar comandos ou adicionar ferramentas auxiliares baixadas exige uma nova revisão, pois isso altera o que o código pode fazer.

Fontes e leituras complementares