Desenvolvedor cria mascote para o Claude Code que bate o pé enquanto o assistente espera resposta

Situação conhecida: você passa uma tarefa grande para o Claude Code, troca para a janela ao lado e, um quarto de hora depois, descobre que o agente parou faz tempo numa pergunta como "posso executar este comando?". A notificação do sistema do Windows até apareceu, mas ficou cinco segundos no canto da tela, enquanto você olhava para outro lado. O autor de um artigo no Habr resolveu o problema de forma radical: criou um mascote impossível de não notar.

O mascote é um pequeno personagem laranja. Primeiro, ele espia pelo canto inferior direito. Se for ignorado, sai por inteiro, fica vermelho e bate o pé na barra de tarefas até você voltar. O visual é divertido, mas a parte mais útil é a engenharia: como saber com segurança que o assistente está esperando alguma coisa.

Como detectar o momento de espera

Na versão de terminal do Claude Code, tudo é simples graças aos hooks. No ~/.claude/settings.json é possível definir um comando que roda em determinado evento, e um JSON com os detalhes chega a ele pelo stdin. Para essa tarefa, serve o evento Notification. O comando envia o stdin via curl para o servidor HTTP local do mascote (127.0.0.1:47821). O trecho final || exit 0 serve para que, com o mascote fechado, o hook termine em silêncio com código 0 e o Claude Code não exiba erro a cada evento. O servidor também descarta requisições com o cabeçalho Origin, para que uma página web qualquer não consiga acessar a porta local.

Com o app desktop do Claude (aba Code), é mais complicado: quando ele pede permissão ou faz uma pergunta, o evento Notification não é enviado. No terminal tudo funcionava, mas no desktop o mascote ficava mudo. Foi preciso assinar também PermissionRequest e PreToolUse, com o matcher AskUserQuestion|ExitPlanMode, para capturar perguntas e a aprovação do plano. Opcionalmente, há também o Stop, que dispara após cada resposta. O próprio mascote registra os hooks, fazendo antes um backup do settings.json (as cinco últimas cópias são mantidas) e sem mexer nas entradas de terceiros.

Há um detalhe: sessões já abertas podem não carregar os novos hooks até serem reiniciadas. Por isso foi adicionada uma segunda fonte de sinal, o banco de notificações do Windows. O sistema grava cada aviso num arquivo SQLite, o wpndatabase.db. Uma vez por segundo, o mascote abre o arquivo para leitura e procura registros do app no formato Claude_*!Claude. O módulo node:sqlite, embutido no Node, dispensa dependências nativas, e o método funciona até com o Claude já em execução, sem injetar nada nele.

Uma janela que aparece, mas não atrapalha

A segunda tarefa é desenhar o overlay. Ele precisa ser transparente, ficar acima de todas as janelas (inclusive as em tela cheia), não aparecer na barra de tarefas, não roubar o foco e deixar os cliques passarem. No Electron, isso é quase todo configuração do BrowserWindow: frame: false, transparent: true, skipTaskbar, alwaysOnTop, focusable: false.

Um truque interessante é o setIgnoreMouseEvents(true, { forward: true }). A janela fica transparente para cliques, mas a página continua recebendo os eventos de movimento do mouse. Quando o cursor entra no mascote (mouseenter), os cliques são reativados; quando o cursor sai, são desativados de novo. Não é preciso calcular manualmente a forma da janela.

Para saber se a janela do Claude está ativa e trazê-la de volta ao primeiro plano, o autor usa o koffi, que chama funções da user32.dll sem node-gyp. A janela ativa é consultada a cada 300 ms, e a carga é imperceptível.

Detalhes que vale copiar

Se o mascote e o aviso padrão do Windows aparecem ao mesmo tempo, o resultado é duplicado. Para isso, há uma opção que desativa os banners apenas do Claude por meio de ShowBanner = 0 no registro. As entradas na central de notificações permanecem, então o banco continua sendo preenchido e o mascote continua enxergando os avisos. O valor anterior da configuração é salvo e restaurado ao desativar a opção, ao sair, ao encerrar a sessão e até após uma falha abrupta, na próxima inicialização.

Entre os problemas de build mencionados no artigo: o electron-builder envia arquivos em paralelo e às vezes cria releases duplicados. Por isso, no GitHub Actions, o release é criado primeiro com gh release create e só depois recebe os arquivos. Na versão portable, process.execPath aponta para uma pasta temporária, então, para a inicialização automática, o caminho é obtido da variável PORTABLE_EXECUTABLE_FILE.

O que fazer com isso

O projeto é gratuito, tem licença MIT e roda no Windows. Mesmo que você não pretenda instalar o mascote, o padrão em si é útil: o hook Notification mais um receptor HTTP local é a forma mínima de conectar o Claude Code a qualquer sinal externo, seja um som, o celular ou uma lâmpada inteligente. A principal limitação é que a solução depende do Windows e do formato interno do banco de notificações, que a Microsoft não documenta como API. Para o Claude desktop, essa fonte funciona como reserva e pode quebrar com uma atualização do sistema. Para a versão de terminal, os hooks bastam.