Clawdmeter Plus

A tiny round AMOLED desk display that shows your live Claude Code usage, the time, the London weather, the health of your background agents, and an animated pixel mascot - and greets you out loud twice a day. It runs on a Waveshare ESP32-S3-Touch-AMOLED-2.16 and talks to a small macOS daemon over Bluetooth LE.

This is a personal fork/extension of the open-source Clawdmeter by Hermann Bjorgvin. It is an independent, unofficial hobby project and is not affiliated with, endorsed by, or sponsored by Anthropic. See Credits & License.

The finished build on my desk. The crisp screenshots further down are captured straight off the panel's framebuffer.

What it shows

The display has two pages. Press the middle PWR button to flip between them.

1. Usage screen (the core)

Your live Claude Code limits, straight from the Anthropic usage API:

• Session limit (the rolling 5-hour window) and weekly limit, as rings/bars
• Current burn rate, so you can see how fast you're spending
• An animated Clawd pixel mascot
• Optional clock in place of the "Usage" title

2. Status screen (this fork's additions)

A bento-style dashboard:

• Clock (12h/24h)
• London weather - current temperature + a condition icon (open-meteo, no API key)
• Tomorrow - tomorrow's forecast high + icon
• Agent dots - five health dots for background Claude agents running in a local tmux session, each with an identity icon. Whichever agent is actively working gets a pulsing orange highlight behind its cell.
• The animated mascot, on this page too

The agent-dots panel is tailored to a specific multi-agent setup (it looks for named tmux windows). If you don't run agents that way the dots simply stay idle - everything else works unchanged. See Customizing.

Controls

Hardware

Other boards in the same family are also supported by the firmware - see Supported boards.

On battery the device sleeps after a few minutes idle to save power and wakes on a PWR press; on USB it stays always-on. A dark screen after a night on battery is normal - just tap PWR.

Assembly

1. If you're adding a battery, plug the LiPo into the board's battery JST connector (check polarity), and seat it in the case.
2. Connect the board to your Mac with a USB-C data cable.
3. That's the whole build - flash the firmware, then run the daemon.

(Enclosure/wiring photos will be added here.)

Flash the firmware

The firmware is a PlatformIO project (C++ / LVGL 9).

Prerequisites

brew install platformio        # provides the `pio` CLI

Flash (convenience script, auto-detects the USB port):

./flash-mac.sh waveshare_amoled_216
# or pin the port explicitly:
./flash-mac.sh waveshare_amoled_216 /dev/cu.usbmodem1101

Flash (raw PlatformIO):

pio run -e waveshare_amoled_216 -t upload

If no /dev/cu.usbmodem* device is found, the cable is charge-only or the board needs download mode - hold BOOT while plugging in, then flash.

Monitor serial output with:

pio device monitor -e waveshare_amoled_216 -b 115200

Run the Mac daemon

The board is just a screen; a small Python daemon (bleak + httpx) is the brains. It reads your Claude usage, fetches the weather, checks agent health, and pushes a compact JSON payload to the device over BLE every ~60 s.

It never stores a token in this repo. On macOS it reads your Claude Code OAuth token from the login Keychain (service Claude Code-credentials) at runtime - the same credential Claude Code itself uses. You just need to be signed in to Claude Code.

Install:

./install-mac.sh

This will:

1. Create a Python virtualenv at daemon/.venv (installs bleak + httpx).
2. Render and load a launchd agent (com.user.claude-usage-daemon) so the daemon starts at login and restarts if it crashes.
3. Optionally install blueutil (auto-recovers the BLE bond after a reflash).
4. Ask a couple of config questions (clock, chime, multi-plan).

Pair the device (once, after flashing):

1. Power on the board.
2. System Settings → Bluetooth → Connect next to "Clawdmeter".
3. macOS will ask to allow Bluetooth for the daemon - click Allow. (A "Keyboard Setup Assistant" window may pop up because the board also exposes BLE HID keys - just close it; don't press any keys.)

The daemon discovers the paired device within ~30 s and starts sending.

Logs & control:

tail -F ~/Library/Logs/claude-usage-daemon.out.log     # "Sending: {…ok:true}" = healthy
launchctl unload -w ~/Library/LaunchAgents/com.user.claude-usage-daemon.plist  # stop
launchctl load   -w ~/Library/LaunchAgents/com.user.claude-usage-daemon.plist  # start

Linux / Windows: the upstream project also ships a systemd unit (daemon/claude-usage-daemon.sh, install.sh) and a Windows daemon + tray (daemon/*_windows.*, install-windows.ps1, daemon/README-windows.md). This fork's extra features are developed and tested on macOS.

Keep the token warm (optional)

The Keychain OAuth token has a short TTL and only refreshes when some Claude Code process makes a call. During long idle stretches it can expire and the device shows stale data until the next activity. daemon/token_keepwarm.sh is a tiny launchd job that spends one throwaway claude -p call only when the token is within ~6 min of expiry, forcing a refresh. Optional but nice for an always-on desk display.

Configuration

Daemon options live in a plain config file that's re-read every poll (no restart needed):

~/.config/claude-usage-monitor/config

Copy daemon/config.example there to start. Keys:

• clock - off / auto / 12 / 24 (show a clock on the usage screen)
• chime - on / off (play a sound through the speaker when your 5-hour session limit resets)
• config_dirs - poll more than one ~/.claude* plan and show whichever is active

The daily voice

The board speaks to you through its onboard speaker twice a day:

• 08:00 - a short motivating morning greeting
• 20:00 - a wind-down / rest message in the evening

Each plays once per day, scheduled off the device clock. The audio is embedded in the firmware as 12 kHz PCM (firmware/src/voice_morning_pcm.h and voice_evening_pcm.h) and played back via the ES8311 codec.

Test the clips over serial (no need to wait for the hour):

voice1   # play the morning clip
voice2   # play the evening clip

Change the times: edit the schedule in firmware/src/main.cpp (search for voice_schedule_tick) - the two lines compare the current minute-of-day against 8 * 60 and 20 * 60. Change those and reflash.

Change the messages / language: the easiest way is the included helper. Type your text, in any language, and it regenerates the header for you:

tools/gen_voice.sh morning en "Good morning! Have a productive day."
tools/gen_voice.sh evening uk "Добрий вечір. Час відпочивати."
# then reflash:
./flash-mac.sh waveshare_amoled_216

It uses free Google Translate TTS (no API key) and writes a 12 kHz / 16-bit / mono PCM header with the right symbol names. Needs ffmpeg (brew install ffmpeg). Keep clips short - they live in the app partition alongside the firmware. Prefer your own audio? Any 12 kHz/16-bit/mono PCM emitted as a C byte array in the same shape works too (mirror bell_pcm.h).

The bundled clips are in English (generic greetings, so anyone can use the build as-is). Swap them for your own language or wording with the command above.

Customizing

• Weather city - the daemon fetches London by default. Edit the open-meteo latitude/longitude (the WX_URL request) in daemon/claude_usage_daemon.py for your city.
• Agent dots - the daemon lights these from named background agents in a local tmux session. If you don't use that setup, the dots stay idle and ha