Claude Desktop Buddy

Cos'è claude-desktop-buddy?

Claude Desktop Buddy (anthropics/claude-desktop-buddy) è un progetto di riferimento ed esempio che mostra come Claude per macOS e Windows si connetta a dispositivi “maker” tramite Bluetooth Low Energy (BLE). È progettato per sviluppatori e maker che vogliono creare hardware in grado di visualizzare prompt di permesso, messaggi recenti e altri stati di interazione da Claude Cowork e Claude Code Desktop.

Il repository è principalmente documentazione ed esempio di firmware per un dispositivo “buddy” BLE. Non serve il codice per costruire hardware concettualmente, ma puoi seguire il riferimento al protocollo wire in REFERENCE.md per implementarlo nel tuo dispositivo BLE.

Caratteristiche Principali

• Riferimento protocollo wire BLE (UUID Nordic UART Service, schemi JSON): ti aiuta a implementare comportamenti compatibili senza indovinare i formati dei messaggi.
• Firmware bridge di esempio per interazioni Claude: collega il dispositivo a Claude così l'hardware reagisce agli stati di interazione.
• Flusso di connessione dispositivo con Developer Mode e finestra Hardware Buddy: documenta come abbinare un dispositivo BLE a bastoncino con Claude Desktop.
• Firmware target ESP32 con framework Arduino: fornisce un punto di partenza concreto per implementazioni embedded.
• Supporto per due modalità di visualizzazione “pet”—ASCII e GIF: il dispositivo di esempio può mostrare un set di animazioni ASCII o streammare un pack di personaggi GIF personalizzati via BLE.

Come Usare claude-desktop-buddy

1. Parti dall'esempio firmware: il firmware hardware targetta ESP32 con framework Arduino. L'esempio del repo dipende dalla libreria M5StickCPlus per display, IMU e driver pulsanti; avrai bisogno di quella board o di una fork che scambia driver per i tuoi pin/layout.
2. Installa PlatformIO Core, poi flasha il firmware esempio con pio run -t upload.
3. Se riflasci un dispositivo già programmato, cancella prima con pio run -t erase && pio run -t upload.
4. Abbina il tuo dispositivo a Claude Desktop:
   • Abilita la developer mode in Claude Desktop (Help → Troubleshooting → Enable Developer Mode).
   • Apri la finestra Hardware Buddy (Developer → Open Hardware Buddy…), clicca Connect e seleziona il tuo dispositivo dall'elenco.
   • Su macOS, la prima connessione richiede il permesso Bluetooth; concedilo.
5. Usa il flusso di pairing per testare prompt di interazione e risposte del dispositivo. Il bridge si ricollega automaticamente quando entrambi i lati sono svegli.

Casi d'Uso

• Costruisci un dispositivo BLE “prompt di permesso”: usa il protocollo di riferimento e il comportamento firmware esempio così il dispositivo può chiedere agli utenti di approvare o negare richieste da Claude.
• Crea un compagno desktop interattivo che risponde allo stato della sessione: l'esempio include un “pet” dispositivo che cambia stato in base a sessione connessa, occupata, approvazione in attesa o interazione completata.
• Distribuisci un controller display a basso consumo per notifiche: l'esempio desk pet descrive il sonno quando non accade nulla e il risveglio all'avvio delle sessioni.
• Personalizza visuali personaggi on-device con un pack GIF: fornisci una cartella con manifest.json più file GIF larghi 96px per stati; l'app streamma il pack via BLE e passa il dispositivo in modalità GIF.
• Itera su asset display senza round-trip BLE: il repo include un workflow tools/flash_character.py che prepara i dati personaggi e li carica via USB direttamente.

FAQ

Devo usare il codice dispositivo fornito per costruire hardware compatibile?
No. Il repository specifica che non serve il codice qui per costruire il tuo dispositivo; REFERENCE.md fornisce i dettagli protocollo wire (UUID, schemi JSON e trasporto push cartella).

Che hardware supporta il firmware esempio?
Il firmware targetta ESP32 con framework Arduino. Come scritto, dipende dalla libreria M5StickCPlus per display, IMU e driver pulsanti, quindi avrai bisogno di quella board o di una fork con driver diversi.

Come abbino un dispositivo a Claude Desktop?
Abilita la developer mode, poi apri la finestra Hardware Buddy (Developer → Open Hardware Buddy…), clicca Connect e scegli il tuo dispositivo. macOS richiede permesso Bluetooth al primo collegamento.

E se il dispositivo BLE non viene rilevato?
Il repo suggerisce di assicurarsi che il bastoncino sia sveglio (premi un pulsante qualsiasi) e di confermare che Bluetooth sia abilitato nel menu impostazioni del bastoncino.

Il dispositivo può visualizzare animazioni personaggi personalizzate?
Sì. L'esempio supporta pet ASCII e pet GIF. Per modalità GIF, fornisci una cartella pack personaggi con manifest.json e GIF larghi 96px per stati; i file stato possono essere un singolo nome file o un array per ruotare animazioni.

Alternative

• Implementa il tuo dispositivo BLE usando il protocollo wire fornito: invece di usare il firmware di riferimento, puoi scrivere uno stack BLE personalizzato che segue gli UUID del Nordic UART Service documentati e gli schemi JSON.
• Usa un'altra piattaforma embedded con BLE ma la stessa logica applicativa: se ESP32 non è il tuo target, puoi adattare il protocollo e la gestione degli stati (sleep/wake, rendering prompt di approvazione e aggiornamenti UI) al tuo microcontrollore preferito.
• Crea un “desktop companion” puramente software senza hardware BLE: se hai bisogno solo di un'interfaccia sul computer, considera un approccio di integrazione solo software anziché un dispositivo fisico di visualizzazione/animazione.