Claude Desktop Buddy

Setup guide

Connect your Claude Desktop Buddy

Use this guide to pair your Buddy with the Claude desktop app on macOS or Windows. The device connects over Bluetooth Low Energy and reconnects automatically after the first successful pairing.

How to connect

The Claude app pairing flow is the same on both platforms. The only platform-specific part is granting Bluetooth permission.

⌘ macOS

  1. Open the Claude desktop app and choose Help → Troubleshooting → Enable Developer Mode.
  2. Open Developer → Open Hardware Buddy....
  3. If you are rebinding this Buddy, remove the old system pairing first in System Settings → Bluetooth. Deleting the device inside Claude Desktop does not remove the macOS Bluetooth binding.
  4. Click Connect, then select your Claude Buddy device when it appears.
  5. When macOS asks for Bluetooth access, click Allow. If you previously denied access, enable it in System Settings → Privacy & Security → Bluetooth.
  6. Start a Claude Code session. The Buddy should wake up and show Claude activity or permission prompts.

⊞ Windows

  1. Open the Claude desktop app and choose Help → Troubleshooting → Enable Developer Mode.
  2. Open Developer → Open Hardware Buddy....
  3. If you are rebinding this Buddy, remove the old system pairing first in Settings → Bluetooth & devices. Deleting the device inside Claude Desktop does not remove the Windows Bluetooth binding.
  4. Click Connect, then choose your Claude Buddy device from the Bluetooth list.
  5. Approve the Windows Bluetooth pairing prompt if it appears. Keep Bluetooth enabled in Settings → Bluetooth & devices.
  6. Start a Claude Code session. After the first pairing, the Buddy should reconnect automatically when it is powered on nearby.

Firmware and build prompt

Use the official firmware source only, then ask your development assistant to verify dependencies, network behavior, and power settings before flashing the device.

Official firmware source

Download or clone the firmware from anthropics/claude-desktop-buddy. 

Help me prepare the Claude Desktop Buddy firmware development and flashing workflow based on the official repository only: https://github.com/anthropics/claude-desktop-buddy. For each step, explain what you checked, what risk you found, and how you handled it.

1. Download or clone firmware source code only from the official GitHub repository. Do not use third-party mirrors, file-sharing links, repackaged ZIP files, or unknown binaries.
2. Audit project dependencies and libraries. Check dependency sources, locked versions, download URLs, install scripts, and build scripts. Pay special attention to supply-chain attack risks such as suspicious postinstall scripts, unpinned versions, binary downloads from unfamiliar domains, obfuscated scripts, or unexpected permission requests.
3. Check whether the firmware or build scripts may report data to unknown third-party endpoints. Search for HTTP, HTTPS, WebSocket, MQTT, analytics, telemetry, reporting, log upload, and similar network code. List every external domain or IP address and explain whether each one is necessary.
4. Identify the currently connected hardware device model. Confirm whether it is an M5Stack StickC Plus2 or an M5Stack S3-series device. Prefer evidence from USB serial information, chip model, board VID/PID, PlatformIO or ESP tooling output, display configuration, IMU configuration, and battery or power-management chip configuration. Do not guess.
5. Based on the detected device model, choose the correct target board, partition table, display driver, button mapping, IMU driver, and power-management configuration. If the repository default target does not match my device, explain the difference and propose the required changes before editing anything.
6. Build a compile environment that matches my current computer. First identify my OS, CPU architecture, Python, Node, PlatformIO, Arduino, ESP-IDF, and related tool versions. Choose an installation approach that does not break my existing environment.
7. Before compiling, show the exact commands. After compiling, report the artifact path, firmware version, target device model, and flashing command.
8. Review and optimize device power usage: screen brightness and timeout, BLE connection interval, idle and sleep strategy, IMU wake behavior, and low-battery behavior. Do not sacrifice basic connection stability.
9. Stop and ask for my confirmation before actually flashing the device. Before confirmation, only perform source review, environment setup, and compile verification.

If it does not connect

Most pairing issues are caused by Bluetooth permission, distance, or another computer already holding the BLE connection.

Quick checks

  1. Restart the Claude desktop app, then reopen Hardware Buddy.
  2. Power the Buddy off and on again.
  3. Move the Buddy close to the computer during pairing.
  4. Disconnect it from any other computer before pairing a new one.
  5. If pairing still behaves strangely after deleting the Buddy in Claude Desktop, forget/remove it from the system Bluetooth device list and bind again.
  6. Recheck Bluetooth permission in macOS or Windows system settings.