HermannBjorgvin/Clawdmeter

ESP32 desk dashboard that shows Claude Code usage

Clawdmeter – A Desk‑Side Claude‑Code Usage Dashboard

What it is – A tiny ESP‑32‑based device that sits on your desk and shows how much of your Claude Code quota you’ve used. It talks to the Claude Code API, pulls the current session and weekly utilization numbers, and displays them on a small colour OLED screen. The device also acts as a Bluetooth‑HID keyboard, letting you trigger Claude Code’s voice‑mode (Space) and mode‑toggle (Shift + Tab) with two side buttons.

How it works (high‑level)

  1. Daemon on your computer – A small Python program runs in the background (as a macOS LaunchAgent, a Linux system‑d user service, or a Windows tray app). It reads your Claude Code OAuth token, makes a single cheap API request, and extracts the usage percentages from the response headers.
  2. BLE transport – The daemon opens a BLE connection to the ESP‑32 and writes a short JSON payload (session %/reset, weekly %/reset, status) to a custom GATT characteristic.
  3. Firmware – The ESP‑32 firmware (built with PlatformIO and LVGL) receives the JSON, updates the on‑screen dashboard, and animates a “Clawd” mascot whose activity level reflects your current usage rate.
  4. Physical controls – Two side buttons send BLE‑HID key events (Space and Shift + Tab) directly to the host, so you can start voice‑mode or toggle Claude Code’s mode without touching the keyboard.

Getting it running

Platform Steps (summary)
macOS 1. Run ./flash-mac.sh <board> to upload firmware. 2. Pair the device in System Settings → Bluetooth. 3. Run ./install-mac.sh – creates a Python venv, installs bleak/httpx, and registers a LaunchAgent that polls usage every 60 s.
Linux Same flash script (./flash.sh). Pair with bluetoothctl. Install daemon with ./install.sh and start via systemctl --user start claude-usage-daemon.
Windows Flash using PlatformIO (pio run -d firmware -e <board> -t upload). Pair through Settings → Bluetooth. Run install-windows.ps1 – creates a venv, installs dependencies, registers a per‑user autostart entry, and launches a tray app.

All three installers set up a virtual environment that contains the required Python libraries (bleak for BLE, httpx for the API call, plus UI helpers on Windows). The daemon logs to a file (or macOS LaunchAgent log) for troubleshooting.

Key features

  • Live usage meter – Shows current session % and weekly % with a simple bar graph.
  • Animated splash screen – Pixel‑art “Clawd” mascot animates faster as your usage climbs; you can cycle animations with the middle button.
  • BLE‑HID shortcuts – One button sends Space (Claude Code voice‑mode push‑to‑talk), the other sends Shift + Tab (mode toggle).
  • Hardware‑agnostic firmware – Core UI code lives in firmware/src/; board‑specific HAL files live under firmware/src/boards/. Adding a new ESP‑32 board only requires a new folder and a PlatformIO environment.
  • Desktop simulator – Build the sim environment to run the UI in an SDL2 window on your PC, useful for UI tweaks without flashing hardware.
  • Open‑source assets – Conversion scripts turn Anthropic’s official “Clawd” sprites and Lucide icons into LVGL‑compatible C arrays.

Who might want this?

  • Claude Code power users who have a subscription and want a quick visual cue of their quota.
  • Hardware hobbyists looking for a concrete example of BLE‑HID + custom GATT services on an ESP‑32 with LVGL graphics.
  • Developers interested in a small, end‑to‑end project that ties a cloud API, a Python daemon, and embedded firmware together.

Caveats & licensing

  • The repository includes Anthropic’s proprietary mascot graphics and brand fonts. While the code itself is open, the assets are not freely licensed, so redistribution may be restricted.
  • The daemon makes a minimal API call (one token of a Haiku) every minute, which is essentially free but still counts against your Claude Code quota.
  • BLE pairing is required; the device does not scan for arbitrary peripherals – it only talks to the host it was paired with.

In short: Clawdmeter is a neat, ready‑to‑use desk gadget that visualises Claude Code usage and gives you quick keyboard shortcuts, built on ESP‑32 hardware, BLE, and a lightweight Python daemon. It’s a genuine, functional project at the intersection of AI‑service monitoring and embedded UI design.

Related

  • Project
    rullerzhou-afk/clawd-on-desk

    Clawd on Desk is a cross‑platform desktop‑pet that watches AI‑coding assistants (Claude Code, Copilot, Gemini, Cursor, etc.) and animates in real time—thinking, typing, building, handling permission requests, and celebrating task completion. It offers hook‑based integration for dozens of agents, permission‑bubble UI, remote approvals (Telegram/Feishu), a dashboard/HUD, and a read‑only mobile PWA companion.

  • Project
    richhickson/claudecodeusage

    Claude Usage is a native macOS menubar app that shows real‑time Claude Code quota usage (session, weekly, monthly) and alerts you when a Claude Code session is waiting for input, letting you jump directly to the terminal tab. It reads your OAuth token from the Keychain, polls Anthropic’s usage endpoint, and uses Claude Code’s hook system for session monitoring.

  • Project
    vivekchand/clawmetry

    ClawMetry is a locally‑run dashboard that auto‑detects up to 30 AI‑agent runtimes (e.g., OpenClaw, NemoClaw, Claude Code) and provides real‑time observability: session transcripts, token/cost breakdowns, flow diagrams, context‑window monitoring, health metrics, alerts, and optional risk‑approval gating. It runs with zero‑config, keeps data on‑premise unless you opt‑in to encrypted cloud sync, and offers free, Starter ($9/node / mo) and Pro ($19/node / mo) plans. Install via `pip install clawmetry && clawmetry` and access the UI at http://localhost:8900.

  • Project
    f-is-h/Usage4Claude

    Usage4Claude is a native macOS menu‑bar app that monitors Anthropic Claude (and optional OpenAI Codex) usage quotas in real time, offering colour‑coded indicators, notifications, multi‑account handling, and full local‑only storage.

  • Dispatch
    Claudoro: Pomodoro Timer for Claude Code

    Claudoro is a feature-rich Pomodoro timer that embeds directly into the Claude Code status line to eliminate context switching during deep work sessions.