Claude Desktop Buddy

claude-desktop-buddy란?

Claude Desktop Buddy (anthropics/claude-desktop-buddy)는 macOS·Windows용 Claude가 Bluetooth Low Energy (BLE)를 통해 “maker devices”에 연결하는 방법을 보여주는 참조 및 예제 프로젝트입니다. Claude Cowork와 Claude Code Desktop에서 오는 권한 프롬프트, 최근 메시지, 기타 상호작용 상태를 표시할 수 있는 하드웨어를 제작하려는 개발자와 메이커를 위해 설계되었습니다.

리포지토리는 주로 BLE “buddy” 장치용 문서와 예제 펌웨어입니다. 하드웨어 개념을 이해하는 데 코드는 필요 없지만, REFERENCE.md의 제공된 와이어 프로토콜 참조를 따라 자신의 BLE 장치에 프로토콜을 구현할 수 있습니다.

주요 기능

• BLE 와이어 프로토콜 참조 (Nordic UART Service UUIDs, JSON 스키마): 메시지 형식을 추측하지 않고 호환 장치 동작을 구현할 수 있습니다.
• Claude 상호작용용 예제 펌웨어 브리지: 장치를 Claude에 연결해 하드웨어가 상호작용 상태에 반응합니다.
• Developer Mode와 Hardware Buddy 창을 사용한 장치 연결 워크플로: 스틱 형태 BLE 장치를 Claude Desktop과 페어링하는 방법을 설명합니다.
• Arduino 프레임워크를 사용한 ESP32 펌웨어 타겟: 임베디드 구현의 구체적인 시작점입니다.
• ASCII와 GIF 두 가지 “pet” 디스플레이 모드 지원: 예제 장치는 ASCII 애니메이션 세트나 BLE를 통해 커스텀 GIF 캐릭터 팩을 스트리밍할 수 있습니다.

claude-desktop-buddy 사용 방법

1. 펌웨어 예제부터 시작: 하드웨어 펌웨어는 Arduino 프레임워크를 사용한 ESP32를 타겟으로 합니다. 리포 예제는 디스플레이, IMU, 버튼 드라이버를 위한 M5StickCPlus 라이브러리에 의존하므로 해당 보드나 핀/레이아웃에 맞게 드라이버를 교체한 포크가 필요합니다.
2. PlatformIO Core를 설치한 후 pio run -t upload으로 예제 펌웨어를 플래시합니다.
3. 이미 프로그래밍된 장치를 재플래시할 때는 먼저 pio run -t erase && pio run -t upload으로 지웁니다.
4. 장치를 Claude Desktop과 페어링:
   • Claude Desktop에서 developer mode 활성화 (Help → Troubleshooting → Enable Developer Mode).
   • Hardware Buddy 창 열기 (Developer → Open Hardware Buddy…), Connect 클릭 후 목록에서 장치 선택.
   • macOS에서는 첫 연결 시 Bluetooth 권한 요청; 허용합니다.
5. 페어링 흐름을 사용해 상호작용 프롬프트와 장치 응답을 테스트합니다. 브리지는 양측이 깨어났을 때 자동 재연결합니다.

사용 사례

• BLE “권한 프롬프트” 장치 제작: 참조 프로토콜과 예제 펌웨어 동작을 사용해 Claude에서 오는 요청을 승인/거부하도록 사용자에게 프롬프트합니다.
• 세션 상태에 응답하는 인터랙티브 데스크톱 컴패니언 제작: 예제는 세션이 연결됨, 바쁨, 승인 대기, 상호작용 완료 여부에 따라 상태가 변경되는 장치 “pet”을 포함합니다.
• 알림용 저전력 디스플레이 컨트롤러 배포: 데스크 pet 예제는 아무 일 없을 때 sleep하고 세션이 시작될 때 깨어납니다.
• GIF 팩으로 온디바이스 캐릭터 비주얼 커스터마이징: manifest.json과 상태별 96px 너비 GIF 파일이 포함된 폴더 제공; 앱이 BLE로 팩을 스트리밍하고 장치를 GIF 모드로 전환합니다.
• BLE 왕복 없이 디스플레이 자산 반복: 리포에 tools/flash_character.py 워크플로가 있어 캐릭터 데이터를 스테이징하고 USB로 직접 업로드합니다.

자주 묻는 질문

제공된 장치 코드를 사용해야 호환 하드웨어를 제작할 수 있나요? 아니요. 리포지토리는 여기에 있는 코드를 사용하지 않아도 자신의 장치를 제작할 수 있다고 명시합니다. REFERENCE.md에 와이어 프로토콜 세부사항 (UUIDs, JSON 스키마, 폴더 푸시 전송)이 있습니다.

예제 펌웨어가 지원하는 하드웨어는? 펌웨어는 Arduino 프레임워크를 사용한 ESP32를 타겟으로 합니다. 작성된 대로 디스플레이, IMU, 버튼 드라이버를 위한 M5StickCPlus 라이브러리에 의존하므로 해당 보드나 다른 드라이버를 사용하는 포크가 필요합니다.

장치를 Claude Desktop과 어떻게 페어링하나요? Developer mode 활성화 후 Hardware Buddy 창 열기 (Developer → Open Hardware Buddy…), Connect 클릭 후 장치 선택. macOS는 첫 연결 시 Bluetooth 권한이 필요합니다.

BLE 장치가 검색되지 않으면? 리포는 스틱이 깨어 있는지 확인 (버튼 누름)하고 스틱 설정 메뉴에서 Bluetooth가 활성화되었는지 확인하라고 제안합니다.

장치가 커스텀 캐릭터 애니메이션을 표시할 수 있나요? 네. 예제는 ASCII pet과 GIF pet을 지원합니다. GIF 모드의 경우 manifest.json과 상태별 96px 너비 GIF가 포함된 캐릭터 팩 폴더를 제공; 상태 파일은 단일 파일명 또는 애니메이션 회전을 위한 배열일 수 있습니다.

대안

• 제공된 와이어 프로토콜을 사용해 자체 BLE 장치 구현: 참조 펌웨어 대신 문서화된 Nordic UART Service UUID와 JSON 스키마를 따르는 커스텀 BLE 스택 작성 가능.
• 동일한 애플리케이션 로직을 가진 다른 BLE 임베디드 플랫폼 사용: ESP32가 목표가 아니라면 프로토콜과 상태 처리(슬립/웨이크, 승인 프롬프트 렌더링, UI 업데이트)를 선호하는 마이크로컨트롤러에 적용.
• BLE 하드웨어 없이 순수 소프트웨어 기반 “데스크톱 컴패니언” 제작: 컴퓨터 인터페이스만 필요하다면 물리적 디스플레이/애니메이션 장치 대신 소프트웨어 전용 통합 방식 고려.