Claude Desktop Buddy

O que é claude-desktop-buddy?

Claude Desktop Buddy (anthropics/claude-desktop-buddy) é um projeto de referência e exemplo que mostra como o Claude para macOS e Windows pode se conectar a dispositivos “maker” via Bluetooth Low Energy (BLE). É projetado para desenvolvedores e makers que querem criar hardware capaz de exibir prompts de permissão, mensagens recentes e outros estados de interação vindos do Claude Cowork e Claude Code Desktop.

O repositório é principalmente documentação e firmware de exemplo para um dispositivo “buddy” BLE. Você não precisa do código para construir hardware conceitualmente, mas pode seguir a referência do protocolo de fio em REFERENCE.md para implementar o protocolo no seu próprio dispositivo BLE.

Principais Recursos

• Referência do protocolo de fio BLE (UUIDs do Nordic UART Service, esquemas JSON): ajuda a implementar comportamento de dispositivo compatível sem adivinhar formatos de mensagem.
• Ponte de firmware de exemplo para interações com Claude: conecta o dispositivo ao Claude para que o hardware reaja a estados de interação.
• Fluxo de conexão de dispositivo com Modo Desenvolvedor e janela Hardware Buddy: documenta como parear um dispositivo BLE tipo stick com Claude Desktop.
• Firmware para ESP32 com framework Arduino: fornece um ponto de partida concreto para implementações embarcadas.
• Suporte a dois modos de exibição “pet”—ASCII e GIF: o dispositivo de exemplo pode mostrar um conjunto de animações ASCII ou transmitir um pacote de personagens GIF personalizado via BLE.

Como Usar claude-desktop-buddy

1. Comece pelo exemplo de firmware: o firmware de hardware mira ESP32 usando o framework Arduino. O exemplo do repo depende da biblioteca M5StickCPlus para drivers de display, IMU e botões; você precisará daquela placa ou um fork que troque drivers para seus pinos/layout.
2. Instale PlatformIO Core, depois grave o firmware de exemplo com pio run -t upload.
3. Se regravando um dispositivo já programado, apague primeiro com pio run -t erase && pio run -t upload.
4. Pareie seu dispositivo com Claude Desktop:
   • Ative o modo desenvolvedor no Claude Desktop (Help → Troubleshooting → Enable Developer Mode).
   • Abra a janela Hardware Buddy (Developer → Open Hardware Buddy…), clique em Connect e selecione seu dispositivo da lista.
   • No macOS, a primeira conexão pede permissão Bluetooth; conceda-a.
5. Use o fluxo de pareamento para testar prompts de interação e respostas do dispositivo. A ponte reconecta automaticamente quando ambos os lados estão acordados.

Casos de Uso

• Crie um dispositivo BLE para “prompt de permissão”: use o protocolo de referência e o comportamento do firmware de exemplo para que o dispositivo solicite aos usuários aprovar ou negar pedidos vindos do Claude.
• Crie um companheiro de desktop interativo que responde a estados de sessão: o exemplo inclui um “pet” de dispositivo que muda de estado com base se uma sessão está conectada, ocupada, aprovação pendente ou interação concluída.
• Implante um controlador de display de baixo consumo para notificações: o exemplo de desk pet descreve dormir quando nada está acontecendo e acordar quando sessões iniciam.
• Personalize visuais de personagens no dispositivo com um pacote GIF: forneça uma pasta com manifest.json mais arquivos GIF de 96px de largura para estados; o app transmite o pacote via BLE e alterna o dispositivo para modo GIF.
• Itere em assets de display sem idas e voltas BLE: o repo inclui um fluxo tools/flash_character.py que prepara dados de personagem e envia via USB diretamente.

FAQ

Preciso usar o código do dispositivo fornecido para construir hardware compatível?
Não. O repositório afirma que você não precisa do código aqui para criar seu próprio dispositivo; REFERENCE.md fornece os detalhes do protocolo de fio (UUIDs, esquemas JSON e transporte de push de pasta).

Que hardware o firmware de exemplo suporta?
O firmware mira ESP32 com framework Arduino. Como está escrito, depende da biblioteca M5StickCPlus para drivers de display, IMU e botões, então você precisará daquela placa ou um fork com drivers diferentes.

Como parear um dispositivo com Claude Desktop?
Ative o modo desenvolvedor, abra a janela Hardware Buddy (Developer → Open Hardware Buddy…), clique em Connect e escolha seu dispositivo. macOS requer permissão Bluetooth na primeira conexão.

E se o dispositivo BLE não for descoberto?
O repo sugere garantir que o stick esteja acordado (pressione qualquer botão) e confirmar que Bluetooth está ativado no menu de configurações do stick.

O dispositivo pode exibir animações de personagens personalizadas?
Sim. O exemplo suporta pets ASCII e pets GIF. Para modo GIF, forneça uma pasta de pacote de personagem com manifest.json e GIFs de 96px de largura para estados; arquivos de estado podem ser um nome de arquivo único ou um array para rotacionar animações.

Alternativas

• Implemente seu próprio dispositivo BLE usando o protocolo de fio fornecido: em vez de usar o firmware de referência, você pode escrever uma pilha BLE personalizada que segue os UUIDs do Nordic UART Service documentados e os esquemas JSON.
• Use outra plataforma embarcada com BLE, mas a mesma lógica de aplicação: se o ESP32 não for o seu alvo, você pode adaptar o protocolo e o tratamento de estados (sleep/wake, renderização de prompt de aprovação e atualizações de UI) ao seu microcontrolador preferido.
• Crie um “desktop companion” puramente baseado em software, sem hardware BLE: se você precisar apenas de uma interface no computador, considere uma abordagem de integração apenas em software em vez de um dispositivo físico de exibição/animação.