Clawdmeter – 책상 옆에 두는 Claude Code 사용량 대시보드

무엇인가요 – 책상 위에 놓을 수 있는 작은 ESP‑32 기반 장치로, Claude Code 사용량(세션 및 주간 비율)을 작은 컬러 OLED 화면에 표시합니다. macOS/Linux/Windows에서 실행되는 Python 데몬이 Claude API에 접속하여 응답 헤더에서 사용량을 추출하고 BLE를 통해 장치로 데이터를 전송합니다. 펌웨어(LVGL UI)는 숫자를 표시하고, 사용량에 따라 활동 수준이 변하는 마스코트 'Clawd'를 애니메이션화합니다. 양쪽의 두 개의 버튼은 BLE‑HID 키보드로 작동하여(스페이스: 음성 모드, Shift + Tab: 모드 전환) 키보드를 건드리지 않고도 바로 작동할 수 있습니다. 리포지토리는 플래시 스크립트, 플랫폼별 설치 프로그램, 데스크톱 시뮬레이터, 다른 ESP‑32 보드로의 이식을 위한 문서를 제공합니다.

작동 방식(개요)

컴퓨터에 있는 데몬 – 작은 Python 프로그램이 백그라운드에서 실행됩니다(맥OS는 LaunchAgent, 리눅스는 systemd 사용자 서비스, 윈도우는 트레이 앱). Claude Code OAuth 토큰을 읽고, 단일 저비용 API 요청을 수행한 후 응답 헤더에서 사용량 퍼센트를 추출합니다.
BLE 전송 – 데몬은 ESP‑32와 BLE 연결을 열고, 사용자 정의 GATT 특성에 짧은 JSON 페이로드(세션 %/리셋, 주간 %/리셋, 상태)를 씁니다.
펌웨어 – ESP‑32 펌웨어(PlatformIO와 LVGL로 구축)는 JSON을 수신하고 화면 대시보드를 업데이트하며, 현재 사용률에 따라 활동 수준이 변하는 'Clawd' 마스코트를 애니메이션화합니다.
물리적 조작 – 양쪽의 두 개의 버튼은 호스트로 직접 BLE‑HID 키 이벤트를 전송하여, 키보드를 건드리지 않고 음성 모드(스페이스) 또는 모드 전환(Shift + Tab)을 시작할 수 있습니다.

실행 방법

플랫폼	단계(요약)
macOS	1. `./flash-mac.sh <board>`를 실행하여 펌웨어 업로드. 2. 시스템 설정 → 블루투스에서 장치 페어링. 3. `./install-mac.sh` 실행 – Python venv 생성, `bleak`/`httpx` 설치, 60초마다 사용량을 페칭하는 LaunchAgent 등록.
Linux	동일한 플래시 스크립트(`./flash.sh`) 사용. `bluetoothctl`로 페어링. `./install.sh`로 데몬 설치 후 `systemctl --user start claude-usage-daemon`로 시작.
Windows	PlatformIO로 플래시(`pio run -d firmware -e <board> -t upload`). 설정 → 블루투스에서 페어링. `install-windows.ps1` 실행 – venv 생성, 종속성 설치, 사용자별 자동 시작 항목 등록, 트레이 앱 실행.

세 가지 설치 프로그램 모두 필요한 Python 라이브러리(bleak은 BLE, httpx는 API 호출, 윈도우에서는 UI 헬퍼)를 포함하는 가상 환경을 설정합니다. 데몬은 로그 파일(또는 macOS LaunchAgent 로그)에 기록되어 문제 해결에 도움이 됩니다.

주요 기능

실시간 사용량 메터 – 세션 %와 주간 %를 간단한 바 그래프로 표시.
애니메이션 스플래시 화면 – 사용량이 증가할수록 빨라지는 픽셀 아트 'Clawd' 마스코트; 중앙 버튼으로 애니메이션 전환 가능.
BLE‑HID 단축키 – 하나의 버튼은 스페이스(음성 모드), 다른 버튼은 Shift + Tab(모드 전환)을 전송.
하드웨어 독립 펌웨어 – 핵심 UI 코드는 firmware/src/에 있으며, 보드별 HAL 파일은 firmware/src/boards/에 있습니다. 새로운 ESP‑32 보드를 추가하려면 새로운 폴더와 PlatformIO 환경만 추가하면 됩니다.
데스크톱 시뮬레이터 – sim 환경을 빌드하여 PC에서 SDL2 윈도우로 UI를 실행할 수 있습니다. 하드웨어 플래시 없이 UI 개선에 유용합니다.
오픈소스 자산 – Anthropic 공식 'Clawd' 스프라이트와 Lucide 아이콘을 LVGL 호환 C 배열로 변환하는 스크립트가 포함되어 있습니다.

누가 이걸 원할까?

Claude Code 고급 사용자 – 구독 중이고 사용량을 빠르게 시각적으로 확인하고 싶은 사람.
하드웨어 애호가 – ESP‑32에서 BLE‑HID + 사용자 정의 GATT 서비스를 구현한 구체적인 예를 찾는 사람.
개발자 – 클라우드 API, Python 데몬, 임베디드 펌웨어를 연결하는 작은 종단 간 프로젝트에 관심 있는 사람.

주의사항 및 라이선스

리포지토리는 Anthropic의 고유 마스코트 그래픽과 브랜드 폰트를 포함합니다. 코드 자체는 오픈소스이지만, 자산은 자유 라이선스가 아니므로 재배포가 제한될 수 있습니다.
데몬은 1분마다 최소한의 API 호출(하이쿠 1개 토큰)을 수행하며, 실질적으로 무료이지만 여전히 Claude Code 사용량에 포함됩니다.
BLE 페어링이 필요합니다. 장치는 임의의 주변 장치를 스캔하지 않습니다. 페어링된 호스트와만 통신합니다.

요약하면: Clawdmeter는 ESP‑32 하드웨어, BLE, 가벼운 Python 데몬으로 구성된 실용적인 책상용 장치로, Claude Code 사용량을 시각화하고 키보드 단축키를 제공합니다. AI 서비스 모니터링과 임베디드 UI 설계의 교차점에 있는 진짜 기능을 갖춘 프로젝트입니다.

HermannBjorgvin/Clawdmeter