Claude Desktop Buddy

What is claude-desktop-buddy?

Claude Desktop Buddy (anthropics/claude-desktop-buddy) is a reference and example project that shows how Claude for macOS and Windows can connect to “maker devices” over Bluetooth Low Energy (BLE). It’s designed for developers and makers who want to build hardware that can display permission prompts, recent messages, and other interaction states coming from Claude Cowork and Claude Code Desktop.

The repository is primarily documentation and example firmware for a BLE “buddy” device. You don’t need the code to build hardware conceptually, but you can follow the provided wire protocol reference in REFERENCE.md to implement the protocol in your own BLE device.

Key Features

• BLE wire protocol reference (Nordic UART Service UUIDs, JSON schemas): helps you implement compatible device behavior without guessing message formats.
• Example firmware bridge for Claude interactions: connects the device to Claude so the hardware can react to interaction states.
• Device connection workflow with Developer Mode and the Hardware Buddy window: documents how to pair a stick-like BLE device with Claude Desktop.
• ESP32 firmware target with Arduino framework: gives a concrete starting point for embedded implementations.
• Support for two “pet” display modes—ASCII and GIF: the example device can show an ASCII animation set or stream a custom GIF character pack over BLE.

How to Use claude-desktop-buddy

1. Start from the firmware example: the hardware firmware targets ESP32 using the Arduino framework. The repo’s example depends on the M5StickCPlus library for display, IMU, and button drivers; you’ll need that board or a fork that swaps drivers for your pin/layout.
2. Install PlatformIO Core, then flash the example firmware using pio run -t upload.
3. If re-flashing an already-programmed device, erase first with pio run -t erase && pio run -t upload.
4. Pair your device with Claude Desktop:
   • Enable developer mode in Claude Desktop (Help → Troubleshooting → Enable Developer Mode).
   • Open the Hardware Buddy window (Developer → Open Hardware Buddy…), click Connect, and select your device from the list.
   • On macOS, the first connection prompts for Bluetooth permission; grant it.
5. Use the pairing flow to test interaction prompts and device responses. The bridge auto-reconnects when both sides are awake.

Use Cases

• Build a BLE “permission prompt” device: use the reference protocol and example firmware behavior so the device can prompt users to approve or deny requests coming from Claude.
• Create an interactive desktop companion that responds to session state: the example includes a device “pet” that changes state based on whether a session is connected, busy, approval is pending, or an interaction is completed.
• Deploy a low-power display controller for notifications: the desk pet example describes sleeping when nothing is happening and waking when sessions start.
• Customize on-device character visuals with a GIF pack: provide a folder containing manifest.json plus 96px-wide GIF files for states; the app streams the pack over BLE and switches the device into GIF mode.
• Iterate on display assets without BLE round-trips: the repo includes a tools/flash_character.py workflow that stages character data and uploads over USB directly.

FAQ

Do I need to use the provided device code to build compatible hardware? No. The repository states that you don’t need the code here to build your own device; REFERENCE.md provides the wire protocol details (UUIDs, JSON schemas, and folder push transport).

What hardware does the example firmware support? The firmware targets ESP32 with the Arduino framework. As written, it depends on the M5StickCPlus library for display, IMU, and button drivers, so you’ll need that board or a fork that uses different drivers.

How do I pair a device with Claude Desktop? Enable developer mode, then open the Hardware Buddy window (Developer → Open Hardware Buddy…), click Connect, and choose your device. macOS requires Bluetooth permission on first connect.

What if the BLE device isn’t discovered? The repo suggests making sure the stick is awake (press any button), and confirming Bluetooth is enabled in the stick’s settings menu.

Can the device display custom character animations? Yes. The example supports ASCII pets and GIF pets. For GIF mode, you supply a character pack folder with manifest.json and 96px-wide GIFs for states; state files can be a single filename or an array to rotate animations.

Alternatives

• Implement your own BLE device using the provided wire protocol: instead of using the reference firmware, you can write a custom BLE stack that follows the documented Nordic UART Service UUIDs and JSON schemas.
• Use another embedded platform with BLE but the same application logic: if ESP32 is not your target, you can adapt the protocol and state handling (sleep/wake, approval prompt rendering, and UI updates) to your preferred microcontroller.
• Build a purely software-based “desktop companion” without BLE hardware: if you only need an interface on the computer, consider a software-only integration approach rather than a physical display/animation device.