Clawdmeter – クラウドコード利用状況を可視化するデスクサイドダッシュボード

何であるか – デスクに置ける小さなESP‑32ベースのデバイスで、Claude Codeの利用クォータがどれだけ使われたかを表示します。このデバイスはClaude Code APIと通信し、現在のセッションおよび週間の利用状況数値を取得して、小さなカラーオリジナルディスプレイに表示します。また、Bluetooth‑HIDキーボードとしても機能し、2つのサイドボタンでClaude Codeの音声モード（Spaceキー）とモード切り替え（Shift + Tab）を簡単に起動できます。

動作原理（概要）

コンピュータ上のデーモン – 小さなPythonプログラムがバックグラウンドで実行されます（macOSではLaunchAgent、Linuxではsystem‑dユーザーサービス、Windowsではトレイアプリ）。このプログラムはClaude CodeのOAuthトークンを読み取り、1回の安価なAPIリクエストを行い、レスポンスヘッダーから利用割合を抽出します。
BLE通信 – デーモンはESP‑32とのBLE接続を開き、カスタムGATT特性に短いJSONペイロード（セッション %/リセット、週間 %/リセット、ステータス）を書き込みます。
ファームウェア – ESP‑32のファームウェア（PlatformIOとLVGLで構築）はJSONを受信し、画面内のダッシュボードを更新し、「Clawd」というマスコットの活動レベルを現在の利用率に応じてアニメーションさせます。
物理的な操作 – 2つのサイドボタンはBLE‑HIDキーベントをホストに直接送信するため、キーボードに触らずとも音声モードを開始したり、モードを切り替えたりできます。

動作させる方法

プラットフォーム	手順（概要）
macOS	1. `./flash-mac.sh <board>` を実行してファームウェアをアップロード。2. System Settings → Bluetooth でデバイスをペアリング。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`）。Settings → Bluetooth でペアリング。`install-windows.ps1` を実行 – venvを作成し、依存関係をインストール、ユーザーごとの自動起動エントリを登録、トレイアプリを起動。

3つのインストーラーは、必要なPythonライブラリ（bleak でBLE、httpx でAPI呼び出し、WindowsではUIヘルパー）を含む仮想環境をセットアップします。デーモンはログファイル（またはmacOS LaunchAgentログ）に記録され、トラブルシューティングに役立ちます。

主な機能

リアルタイム利用メーター – セッション%と週間%をシンプルなバー図で表示。
アニメーションスプラッシュ画面 – 利用率が上がるほどピクセルアートの「Clawd」マスコットが速くアニメーション。中央ボタンでアニメーションを切り替え可能。
BLE‑HIDショートカット – 1つのボタンでSpaceキー（Claude Code音声モードのプッシュツーティーク）、もう1つのボタンで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