Claude Desktop Buddy

¿Qué es claude-desktop-buddy?

Claude Desktop Buddy (anthropics/claude-desktop-buddy) es un proyecto de referencia y ejemplo que muestra cómo Claude para macOS y Windows puede conectarse a dispositivos “maker” mediante Bluetooth Low Energy (BLE). Está diseñado para desarrolladores y makers que quieran construir hardware capaz de mostrar prompts de permisos, mensajes recientes y otros estados de interacción provenientes de Claude Cowork y Claude Code Desktop.

El repositorio es principalmente documentación y firmware de ejemplo para un dispositivo “buddy” BLE. No necesitas el código para construir hardware conceptualmente, pero puedes seguir la referencia del protocolo de cableado en REFERENCE.md para implementar el protocolo en tu propio dispositivo BLE.

Características clave

• Referencia del protocolo de cableado BLE (UUIDs del servicio Nordic UART, esquemas JSON): te ayuda a implementar comportamiento de dispositivo compatible sin adivinar formatos de mensajes.
• Puente de firmware de ejemplo para interacciones con Claude: conecta el dispositivo a Claude para que el hardware reaccione a estados de interacción.
• Flujo de conexión de dispositivos con Modo Desarrollador y la ventana Hardware Buddy: documenta cómo emparejar un dispositivo BLE tipo stick con Claude Desktop.
• Firmware para ESP32 con framework Arduino: proporciona un punto de partida concreto para implementaciones embebidas.
• Soporte para dos modos de visualización “pet”—ASCII y GIF: el dispositivo de ejemplo puede mostrar un conjunto de animaciones ASCII o transmitir un pack de personajes GIF personalizados por BLE.

Cómo usar claude-desktop-buddy

1. Comienza con el ejemplo de firmware: el firmware de hardware apunta a ESP32 usando el framework Arduino. El ejemplo del repo depende de la biblioteca M5StickCPlus para drivers de pantalla, IMU y botones; necesitarás esa placa o un fork que cambie drivers para tus pines/disposición.
2. Instala PlatformIO Core, luego flashea el firmware de ejemplo con pio run -t upload.
3. Si reflasheas un dispositivo ya programado, borra primero con pio run -t erase && pio run -t upload.
4. Empareja tu dispositivo con Claude Desktop:
   • Activa el modo desarrollador en Claude Desktop (Help → Troubleshooting → Enable Developer Mode).
   • Abre la ventana Hardware Buddy (Developer → Open Hardware Buddy…), haz clic en Connect y selecciona tu dispositivo de la lista.
   • En macOS, la primera conexión pide permiso de Bluetooth; otórgalo.
5. Usa el flujo de emparejamiento para probar prompts de interacción y respuestas del dispositivo. El puente se reconecta automáticamente cuando ambos lados están despiertos.

Casos de uso

• Construye un dispositivo BLE para “prompts de permiso”: usa el protocolo de referencia y el comportamiento del firmware de ejemplo para que el dispositivo pida a los usuarios aprobar o denegar solicitudes de Claude.
• Crea un compañero de escritorio interactivo que responde al estado de sesión: el ejemplo incluye un “pet” de dispositivo que cambia de estado según si una sesión está conectada, ocupada, pendiente de aprobación o una interacción completada.
• Despliega un controlador de pantalla de bajo consumo para notificaciones: el ejemplo de desk pet describe dormir cuando no pasa nada y despertar cuando inician sesiones.
• Personaliza visuales de personajes en el dispositivo con un pack GIF: proporciona una carpeta con manifest.json más archivos GIF de 96px de ancho para estados; la app transmite el pack por BLE y cambia el dispositivo a modo GIF.
• Itera en assets de visualización sin viajes de ida y vuelta por BLE: el repo incluye un flujo tools/flash_character.py que prepara datos de personajes y sube por USB directamente.

Preguntas frecuentes

¿Necesito usar el código del dispositivo proporcionado para construir hardware compatible?
No. El repositorio indica que no necesitas el código aquí para construir tu propio dispositivo; REFERENCE.md proporciona los detalles del protocolo de cableado (UUIDs, esquemas JSON y transporte de carpetas).

¿Qué hardware soporta el firmware de ejemplo?
El firmware apunta a ESP32 con el framework Arduino. Tal como está escrito, depende de la biblioteca M5StickCPlus para drivers de pantalla, IMU y botones, por lo que necesitarás esa placa o un fork con drivers diferentes.

¿Cómo emparejo un dispositivo con Claude Desktop?
Activa el modo desarrollador, luego abre la ventana Hardware Buddy (Developer → Open Hardware Buddy…), haz clic en Connect y elige tu dispositivo. macOS requiere permiso de Bluetooth en la primera conexión.

¿Qué pasa si no se descubre el dispositivo BLE?
El repo sugiere asegurarte de que el stick esté despierto (presiona cualquier botón) y confirmar que Bluetooth esté activado en el menú de ajustes del stick.

¿Puede el dispositivo mostrar animaciones de personajes personalizadas?
Sí. El ejemplo soporta pets ASCII y pets GIF. Para modo GIF, suministra una carpeta de pack de personajes con manifest.json y GIFs de 96px de ancho para estados; los archivos de estado pueden ser un nombre de archivo único o un array para rotar animaciones.

Alternativas

• Implementa tu propio dispositivo BLE usando el protocolo de cableado proporcionado: en lugar de usar el firmware de referencia, puedes escribir una pila BLE personalizada que siga los UUID del servicio Nordic UART documentados y los esquemas JSON.
• Usa otra plataforma embebida con BLE pero la misma lógica de aplicación: si ESP32 no es tu objetivo, puedes adaptar el protocolo y el manejo de estados (suspensión/despertar, renderizado de prompts de aprobación y actualizaciones de UI) a tu microcontrolador preferido.
• Crea un “compañero de escritorio” puramente basado en software sin hardware BLE: si solo necesitas una interfaz en la computadora, considera un enfoque de integración solo de software en lugar de un dispositivo de visualización/animación físico.