Clawdmeter: an ESP32 desk dashboard for Claude Code usage

What Clawdmeter actually measures

Claude Code exposes usage as two numbers that matter to a heavy user: session utilization and weekly utilization. Clawdmeter puts both on a small screen that sits on your desk, so you do not have to open a terminal or a web page to see where you stand. The Usage view is the whole point of the device; everything else is decoration around it.

The decoration is deliberate. The splash screen plays pixel-art Clawd animations, and the README states the animations get busier as your usage rate climbs. The firmware also auto-rotates animations every 20 seconds within the current usage-rate group, so a long stretch on the splash is not one animation on loop. The two side buttons send Space and Shift+Tab over BLE HID, which map to Claude Code's voice mode and mode-toggle shortcuts. That is a narrow feature set, and it is aimed at one person: someone who runs Claude Code all day and wants an ambient signal rather than another dashboard tab.

The BLE split between firmware and host daemon

Clawdmeter is two programs. The firmware runs on the ESP32 and owns the screen, the touch handling, the animations and the BLE HID buttons. A host daemon runs on your computer, reads your Claude OAuth token, polls usage every 60 seconds, and pushes the result to the display over Bluetooth. The device never talks to Anthropic's servers itself.

That split has consequences worth understanding before you buy a board. The token stays on the host, which is where it already lives: on macOS the daemon reads it from the Keychain under the service name Claude Code-credentials, and on Windows it reads %USERPROFILE%\.claude\.credentials.json with fallbacks to %LOCALAPPDATA%\Claude\ and %APPDATA%\Claude\. The display is a peripheral with no credentials of its own, so a stolen desk toy reveals nothing. The cost is that the numbers freeze whenever the host is asleep, shut down, or has its Bluetooth off, and the README notes the daemon picks up a newly connected device on its next poll, roughly 60 seconds later.

The pairing model is also stricter than most Bluetooth gadgets. On macOS the daemon only ever connects to the peripheral that Mac is paired and connected to; it never scans for a nearby device. On Linux you pair once with bluetoothctl and trust the address. Re-pairing is a physical action: hold the power button for 3 seconds, then release, and the device clears its saved bond and re-advertises.

Flashing a supported board and running the daemon

The firmware is a thin HAL with per-board folders under firmware/src/boards/. The README states that main.cpp, ui.cpp and splash.cpp never need to change when you add a board; you drop in a new folder and a new PlatformIO env. Supported out of the box: the Waveshare ESP32-S3-Touch-AMOLED-2.16, ESP32-C6-Touch-AMOLED-2.16, ESP32-S3-Touch-AMOLED-1.8, ESP32-C6-Touch-AMOLED-1.8, ESP32-S3-Touch-AMOLED-2.06, ESP32-S3-Touch-LCD-1.54 and ESP32-S3-Touch-LCD-4.

Prerequisites are PlatformIO CLI plus curl, bluetoothctl and busctl on Linux, python3 on macOS, and python3 3.11+ on Windows. You also need Claude Code with an active subscription. Flashing takes a board env name and an optional serial port. On Linux:

./flash.sh waveshare_amoled_216                  # ESP32-S3 2.16" (defaults to /dev/ttyACM0)
./flash.sh waveshare_amoled_216_c6               # ESP32-C6 2.16" variant
./flash.sh waveshare_amoled_18  /dev/ttyACM1     # ESP32-S3 1.8" (or pass an explicit USB serial port)

The env name is required; running ./flash.sh with no arguments prints the available envs scraped from firmware/platformio.ini. The macOS equivalent is ./flash-mac.sh with the same board env names, and it auto-detects /dev/cu.usbmodem* unless you pass a port. After flashing, pair the device once. On Linux the README gives this sequence:

bluetoothctl scan le
bluetoothctl pair F4:12:FA:C0:8F:E5
bluetoothctl trust F4:12:FA:C0:8F:E5

On macOS you connect through System Settings, Bluetooth, next to the entry named Clawdmeter. Then install the daemon:

./install.sh
systemctl --user start claude-usage-daemon
systemctl --user status claude-usage-daemon
journalctl --user -u claude-usage-daemon -f

On macOS the installer creates a venv in daemon/.venv/, installs bleak and httpx, renders a LaunchAgent to ~/Library/LaunchAgents/com.user.claude-usage-daemon.plist, loads it, and launches the first run interactively so macOS prompts for Bluetooth permission. On Windows, install-windows.ps1 sets up a venv with bleak, httpx and pystray, and the tray app starts at login. The README is explicit that Windows must be native, not WSL, and that the repo must sit on a native Windows path.

Once the daemon is up, expect the Usage view to populate on the next poll rather than instantly. Tapping the screen anywhere toggles between the splash and the Usage view.

Where Clawdmeter is the wrong tool

The obvious limit is hardware. If you do not own one of the seven listed Waveshare boards, Clawdmeter is not a download you can try; it is a porting project. The repository documents the path in docs/porting/adding-a-board.md and docs/porting/hal-contract.md, and the README asks you to check whether a pull request already exists for your alternative hardware before opening a new one, because QA feedback on an existing port is more valuable than a duplicate. That is a reasonable policy and also a signal: unsupported boards are community work, not a supported configuration.

Second, the device is only as live as the host. The daemon polls every 60 seconds, so the display is a lagging indicator by design, and it goes stale the moment the host sleeps. If you want a warning before you hit a limit, a 60-second poll on a screen you have to glance at is a weaker signal than a shell prompt or a notification.

Third, the feature set is fixed and small. There is no documented history, no alerting, no logging of past usage on the device. It shows current session and weekly utilization and nothing else. Anyone expecting a general-purpose Claude analytics panel will be disappointed by a two-number screen with animated pixel art on top.

Clawdmeter versus reading usage in the terminal

The realistic alternative is not another ESP32 project. It is checking usage the way you already check it: in the Claude Code session itself, or in whatever web view your subscription provides. That approach costs nothing, needs no board, no PlatformIO toolchain, no Bluetooth pairing and no daemon running in the background.

The difference is attentional, not technical. A terminal check is a deliberate action you take when you think of it. Clawdmeter is ambient: it is on your desk, it is always showing the last poll, and the splash animation gets busier as the rate climbs, which is a signal you absorb without asking for it. Whether that is worth a board, a flashed firmware, a 60-second daemon and a Bluetooth pairing ritual is a personal call. If you already own the hardware and enjoy the build, the trade is easy. If you would be buying a board specifically for this, the terminal wins on cost and the README offers no counter-argument.

Maintenance cost, licence and what the repository does not say

The last push to the default branch was on 2026-09-10, and the repository is not archived. There are no retrieved releases, so there is no versioned artifact to pin and no changelog to read; you install from the repository at whatever state main is in. Upgrades mean re-running the flash script and, on macOS, re-running the installer, which re-renders the LaunchAgent. Nothing in the README describes a rollback path for a bad flash, and the README does not document a firmware version check or an over-the-air update mechanism, so treat re-flashing over USB as the recovery route.

The licence is not stated in the repository. The README carries affiliate links on the Waveshare product URLs, which is worth knowing before you assume the hardware recommendations are neutral. It also credits the macOS host port to Chris Davidson (@lorddavidson). If you plan to redistribute the firmware or ship it inside a product, resolve the licence question with the repository owner first; that is a factual gap, not a legal opinion.

Editorial conclusion

Adopt Clawdmeter if you already own one of the listed Waveshare AMOLED or LCD boards, run Claude Code on Linux, macOS or native Windows, and want session and weekly utilization visible without alt-tabbing. Skip it if you have no board on the supported list, expect a finished consumer product, or need a supported path on hardware the repository does not list. Before buying anything, read docs/porting/adding-a-board.md and docs/porting/hal-contract.md to confirm your board's interfaces are covered, and check whether a pull request already exists for your hardware port, since the README asks for QA feedback on an existing port rather than duplicate work.

Frequently asked questions

Official sources

1. HermannBjorgvin/Clawdmeter on GitHub
2. Issues
3. README