Clawdmeter – 一個放置在桌面上的 Claude Code 使用狀況儀表板

它是什麼 – 一個小巧的基於 ESP‑32 的裝置，放在你的桌上，顯示你已使用多少 Claude Code 配額。它與 Claude Code API 通訊，取得目前的 會話 和 每週 使用量數值，並在小型彩色 OLED 屏幕上顯示。該裝置同時作為 Bluetooth‑HID 鍵盤，讓你透過兩個側邊按鈕觸發 Claude Code 的語音模式（空格鍵）和模式切換（Shift + Tab）。

---

如何運作（高階概覽）

1. 電腦上的守護程式 – 一個小型 Python 程式在背景執行（macOS 上為 LaunchAgent，Linux 上為 system‑d 使用者服務，Windows 上為系統匣應用程式）。它讀取你的 Claude Code OAuth 憑證，發出單一低成本的 API 請求，並從回應標頭中提取使用百分比。
2. BLE 傳輸 – 守護程式開啟與 ESP‑32 的 BLE 連接，將一段簡短的 JSON 負載（會話 %/重置、每週 %/重置、狀態）寫入自訂的 GATT 特性。
3. 固件 – ESP‑32 固件（使用 PlatformIO 與 LVGL 建構）接收 JSON，更新螢幕上的儀表板，並動畫化一個「Clawd」吉祥物，其活躍程度反映你目前的使用速率。
4. 實體控制 – 兩個側邊按鈕直接透過 BLE‑HID 發送鍵盤事件（空格鍵與 Shift + Tab）至主機，讓你無需碰觸鍵盤即可啟動語音模式或切換 Claude Code 模式。

---

如何啟動執行

平台	步驟（摘要）
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 呼叫，Windows 上還有 UI 助手）的虛擬環境。守護程式會將日誌輸出至檔案（或 macOS LaunchAgent 日誌）以利除錯。

---

主要功能

• 即時使用量計量器 – 以簡單的條形圖顯示目前會話百分比與每週百分比。
• 動畫開機畫面 – 像素藝術「Clawd」吉祥物會隨著使用量上升而加快動畫；你可以透過中間按鈕切換動畫。
• BLE‑HID 快捷鍵 – 一個按鈕發送空格鍵（Claude Code 語音模式按鍵通話），另一個按鈕發送 Shift + Tab（模式切換）。
• 硬體無關的固件 – 核心 UI 程式碼位於 firmware/src/；板卡特定的 HAL 檔案位於 firmware/src/boards/。新增支援新的 ESP‑32 雜湊僅需新增資料夾與 PlatformIO 環境。
• 桌面模擬器 – 建構 sim 環境，可在 PC 上的 SDL2 窗口中執行 UI，方便在不閃存硬體的情況下調整介面。
• 開源資源 – 轉換腳本可將 Anthropic 官方的「Clawd」角色圖與 Lucide 圖示轉換為 LVGL 相容的 C 陣列。

---

哪些人可能會想要這個？

• Claude Code 高階使用者，擁有訂閱服務，希望快速獲得配額使用狀況的視覺提示。
• 硬體愛好者，尋找 ESP‑32 上 BLE‑HID + 自訂 GATT 服務的實際範例，搭配 LVGL 圖形介面。
• 開發者，對一個小型、端到端的專案感興趣，能將雲端 API、Python 守護程式與嵌入式固件整合在一起。

---

注意事項與授權

• 倉儲包含 Anthropic 的專有吉祥物圖形與品牌字型。雖然程式碼本身是開源的，但資源並非自由授權，因此再發行可能受到限制。
• 守護程式每分鐘發出一次最小的 API 呼叫（一個 Haiku 的 token），基本上是免費的，但仍會計入你的 Claude Code 配額。
• 必須進行 BLE 配對；裝置 不會 掃描任意外設 – 它僅與已配對的主機通訊。

---

總結來說： Clawdmeter 是一個精巧、即開即用的桌面小工具，可視化 Claude Code 使用狀況，並提供快速鍵盤捷徑，基於 ESP‑32 硬體、BLE 與輕量級 Python 守護程式建構。這是一個真實、功能完整的專案，位於 AI 服務監控與嵌入式 UI 設計的交界處。