Clawdmeter 소개
Claude Code로 일하다 보면 5시간 세션 한도와 주간 한도가 얼마나 남았는지 궁금해서 터미널 명령을 두드리게 됩니다. Clawdmeter는 그 숫자를 책상 위의 작은 화면에 상시 띄워 두는 ESP32 기반 오픈소스 가젯입니다. 개발자 Hermann Björgvin이 자기 책상용으로 만든 프로젝트로, Waveshare의 ESP32-S3/C6 터치 AMOLED 보드에서 동작하며 컴퓨터와는 블루투스로 연결됩니다.
화면은 단순한 게이지에 그치지 않습니다. 대기 화면에서는 픽셀 아트 Clawd 애니메이션이 재생되는데, 사용량 증가 속도가 빨라질수록 더 분주한 동작의 애니메이션으로 바뀝니다. 애니메이션 스프라이트는 @amaanbuilds의 claudepix 라이브러리에서 가져왔습니다. 기기 양옆의 물리 버튼 두 개는 BLE HID 키보드 입력으로 Space와 Shift+Tab을 보내 Claude Code의 음성 모드와 모드 전환 단축키로 쓸 수 있습니다.
지원 보드는 Waveshare ESP32-S3/C6 Touch AMOLED 2.16인치와 1.8인치 네 종이 기본이고, 펌웨어가 보드별 폴더로 분리된 얇은 HAL 구조라 다른 보드로의 포팅도 열려 있습니다. 새 보드 추가 절차는 저장소의 docs/porting/adding-a-board.md에 정리되어 있습니다.
Clawdmeter의 동작 방식
호스트 컴퓨터에서 도는 데몬이 모든 일을 합니다. macOS에서는 키체인, Linux에서는 ~/.claude/.credentials.json, Windows에서는 %USERPROFILE%\.claude\.credentials.json 에서 Claude Code의 OAuth 토큰을 읽고, api.anthropic.com/v1/messages 에 Haiku 토큰 1개짜리 최소 호출을 보냅니다. 사용량 수치는 응답 헤더(anthropic-ratelimit-unified-5h-utilization 등)에서 그대로 뽑아내므로 추가 비용이 사실상 들지 않습니다.
데몬은 60초마다 사용량을 폴링해 BLE GATT 특성으로 JSON을 밀어 넣고, 펌웨어가 이를 파싱해 LVGL 대시보드를 갱신합니다. 펌웨어는 최근 5분 동안의 세션 사용률 변화 속도도 추적해 그에 맞는 분위기 그룹의 대기 애니메이션을 고릅니다. 화면을 탭하면 대기 화면과 사용량 화면(세션·주간 사용률)이 전환되고, 전원 버튼을 3초 눌렀다 떼면 저장된 블루투스 본딩을 지우고 페어링 모드로 들어갑니다.
Clawdmeter 설치 및 사용법
Linux(Ubuntu 테스트), macOS, Windows 10/11을 지원하며 PlatformIO CLI와 활성 구독 상태의 Claude Code가 필요합니다. 펌웨어 플래싱은 보드 환경 이름을 지정해 스크립트 하나로 끝납니다.
# Linux
./flash.sh waveshare_amoled_216
# macOS
./flash-mac.sh waveshare_amoled_216
이후 기기를 블루투스로 페어링하고 데몬을 설치합니다. Linux는 systemd 사용자 서비스, macOS는 LaunchAgent로 등록됩니다.
# Linux
./install.sh
systemctl --user start claude-usage-daemon
# macOS
./install-mac.sh
Windows는 WSL 없이 네이티브로 동작합니다. install-windows.ps1 스크립트가 가상 환경을 만들고 로그인 시 자동 시작되는 시스템 트레이 앱을 등록하며, 트레이 아이콘의 색으로 연결 상태(초록 연결, 주황 스캔 중, 빨강 오류)를 보여줍니다. macOS 호스트 구성 요소는 Chris Davidson이 포팅해 기여했습니다.
Clawdmeter GitHub 저장소
더 읽어보기
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다. 
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 