Clawdmeter's Local Claude Code Telemetry Loop

Clawdmeter looks like a novelty at first: an ESP32 AMOLED display with animated Clawd art and a usage meter for Claude Code. That is not the reason it belongs in a Codex-focused magazine. The useful part is the boundary it draws around agent-workflow telemetry. A host daemon reads Claude Code credentials, asks Anthropic for a tiny response, extracts rate-limit headers, sends a compact JSON payload over BLE, and lets firmware render the result on a physical device. That makes it a good case study for when a coding-agent workflow should leave the chat window and become local infrastructure.

The old version of this article failed because it treated the project as another productivity gadget. The source material supports a sharper reading: Clawdmeter is valuable if you want ambient usage pressure, physical Claude Code shortcuts, and a reference implementation for a local telemetry peripheral. It is a poor fit if your environment cannot allow a third-party daemon to read OAuth credentials or if you need a cleanly licensed product surface.

The Boundary It Creates

The project README says the device shows session and weekly utilization on Waveshare ESP32-S3/C6 AMOLED boards and pairs over Bluetooth. The important workflow change is that usage state becomes ambient. Instead of asking an agent or opening a usage page, the developer can see remaining budget and reset timing on the desk. That is useful for long Claude Code sessions where the failure mode is not one bad prompt but creeping rate-limit pressure across many tool calls.

The boundary is local, not cloud. The daemon reads Claude credentials on the same host, polls Anthropic, and writes to a BLE characteristic. There is no hosted dashboard layer in the source. That makes the project more inspectable than a SaaS usage meter, but it also means the local machine, the daemon, the paired peripheral, and the firmware are all part of the trust chain. For Codex or Claude Code practitioners, that is the first adoption question: do you want usage telemetry handled by local code you can read, or would a software-only dashboard with fewer moving parts be easier to govern?

What the Daemon Is Allowed to See

On macOS, install-mac.sh checks for a Keychain item named Claude Code-credentials, creates daemon/.venv/, installs bleak and httpx, renders ~/Library/LaunchAgents/com.user.claude-usage-daemon.plist, and loads it with launchd. On Linux, the README points to ~/.claude/.credentials.json and a systemctl --user daemon path. In both cases the host process is not just reading a public status endpoint; it is operating with credentials that deserve the same review as any local tool in the agent stack.

The daemon code makes a minimal POST to https://api.anthropic.com/v1/messages with a one-token Haiku request, then relies on rate-limit headers such as five-hour utilization. That is a clever way to avoid scraping UI state, but it also means the monitoring loop is coupled to an authenticated API call and to header semantics. Before adopting it, verify the exact model name, beta header, polling interval, and response headers against your current Claude Code account behavior. A 60-second polling loop is reasonable for a desk display, but it should not become hidden traffic you forget during incident review.

Useful local checks are explicit in the README:

launchctl list | grep claude-usage
tail -F ~/Library/Logs/claude-usage-daemon.out.log
launchctl unload ~/Library/LaunchAgents/com.user.claude-usage-daemon.plist
launchctl load -w ~/Library/LaunchAgents/com.user.claude-usage-daemon.plist

The BLE Contract Is Small Enough to Audit

Clawdmeter's firmware exposes a custom GATT service 4c41555a-4465-7669-6365-000000000001 beside the standard HID keyboard service. The host writes usage data to RX 4c41555a-4465-7669-6365-000000000002; the TX and refresh characteristics handle notify-style feedback. The payload is deliberately compact:

{ "s": 45, "sr": 120, "w": 28, "wr": 7200, "st": "allowed", "ok": true }

That contract is the part worth borrowing even if you never build the desk gadget. It keeps the host daemon responsible for authenticated Anthropic access and makes the ESP32 responsible for rendering, buttons, and display state. It does not ask firmware to understand Claude accounts. It also gives you concrete failure tests: does ok=false render visibly, do stale reset minutes stay obvious, and does the device recover when BLE reconnects after the host sleeps?

The two side buttons are a separate boundary. The README says they send Space and Shift+Tab as BLE HID keyboard input. That is convenient for Claude Code voice mode and mode switching, but it is not scoped to Claude Code. HID reports go to whichever window has focus. That should be treated as a feature for a personal workstation and a risk for shared machines, pair-programming setups, or locked-down environments.

Install Path and Verification

A serious install plan has two tracks: firmware and host daemon. Treat them as separate acceptance gates.

For macOS firmware, pick the board env from firmware/platformio.ini and flash that exact target:

./flash-mac.sh waveshare_amoled_216
./flash-mac.sh waveshare_amoled_18 /dev/cu.usbmodem1101

If you want the lower-level PlatformIO check before flashing, run the build directly:

pio run -d firmware -e waveshare_amoled_216
pio run -d firmware -e waveshare_amoled_18

Then pair the device in System Settings as Claude Controller and install the host daemon:

./install-mac.sh
launchctl list | grep claude-usage
tail -F ~/Library/Logs/claude-usage-daemon.out.log

The installer intentionally runs the daemon interactively once so macOS can grant Bluetooth permission before launchd takes over. That detail matters. If you skip it and only debug the background service, you can misdiagnose a permission failure as a BLE or firmware issue. To stop and restart the service during testing, use the actual LaunchAgent path:

launchctl unload ~/Library/LaunchAgents/com.user.claude-usage-daemon.plist
launchctl load -w ~/Library/LaunchAgents/com.user.claude-usage-daemon.plist

On Linux the equivalent flow is explicit too:

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

For a Codex-style workflow, the acceptance checklist should be concrete: firmware flashes with the expected PlatformIO env, the device pairs as Claude Controller, the daemon log shows scans and writes, the display updates after a 60-second poll, button HID events only fire when intended, and the usage screen handles API failures without pretending data is fresh. Those are better success criteria than asking whether the device looks good on a desk.

Maintenance Is a Firmware Problem, Not Just a Tool Install

Clawdmeter is not a single npm package. CLAUDE.md describes an ESP32-S3 firmware architecture where each board lives under firmware/src/boards/<name>/, shared code calls HAL headers under firmware/src/hal/, and PlatformIO build_src_filter selects one board folder per environment. The porting docs reinforce the same rule: a new board should add a board folder and a [env:...] block in firmware/platformio.ini, not sprinkle #ifdef BOARD_* through shared UI code.

That architecture is a strength if you are comfortable with embedded maintenance. It gives a clean boundary between display, touch, input, power, IMU, UI, BLE, and splash rendering. It is a liability if you only wanted a usage meter. The docs call out concrete traps: OPI PSRAM is required, some panels need IO expanders released before gfx->begin(), LVGL 9 fonts need manual patching after lv_font_conv, and touch coordinate transforms belong inside per-board touch.cpp. These are not abstract caveats. They are the difference between a visible display and a black panel that appears to do nothing.

The right comparison is therefore not only Clawdmeter versus another dashboard. It is Clawdmeter versus the operational cost of owning a tiny hardware product in your personal agent setup.

What It Beats and What It Loses To

A software-only Claude usage dashboard wins on installation and governance. It can run in a terminal, browser, or menu bar, and it does not need firmware flashing, BLE pairing, HID permissions, display drivers, or asset review. If the team need is reporting, trend history, or cost accountability, keep the problem in software and give it normal logging and access-control treatment.

Clawdmeter wins in a narrower setting: a single developer running long Claude Code sessions who wants usage pressure to be visible without stealing terminal space. A physical meter changes behavior because it is always in the room. That is different from a dashboard tab you stop checking. The device also turns two Claude Code shortcuts into hardware buttons, which can matter for voice-mode use if the desk setup is stable and the focused-window behavior is understood.

A generic ESP32 system monitor loses the Claude-specific semantics. It may show CPU, network, or battery, but it does not understand anthropic-ratelimit-unified-5h-utilization, session reset minutes, weekly reset minutes, or allowed versus limited state. Clawdmeter is interesting because its wire contract is shaped around those agent-workflow states. That is also why it should not be generalized casually. Once a local daemon can read an agent's credentials and emit keyboard events, the tool has crossed from decoration into workstation infrastructure.

Security and Licensing Gates

The security gate is straightforward: the daemon reads Claude Code credentials and sends authenticated requests. Keep it local, inspect the exact code path, and do not deploy it onto a machine where credential access requires central review unless that review has happened. If you use both Codex and Claude Code on the same workstation, make the ownership boundary explicit in AGENTS.md or local runbooks: this daemon belongs to Claude usage telemetry, not to project code execution.

The licensing gate is equally explicit. The README warns that the repository uses Anthropic brand fonts and copyrighted Clawd mascot assets without permission, even though the code itself is non-proprietary. The splash-animation tools scrape claudepix data and the tools README says to confirm reuse before redistributing output. That makes Clawdmeter fine as a personal experiment or internal reference, but risky as a public fork, product feature, conference giveaway, or company-standard hardware kit unless the assets are replaced or licensed.

This is where the magazine verdict differs from a repository summary: the project is useful precisely because it is specific, but that specificity carries credential, Bluetooth, HID, hardware, and asset constraints.

Adoption Verdict

Use Clawdmeter when you want ambient Claude Code usage awareness on a personal workstation and you are comfortable reviewing Python daemon code, BLE firmware, PlatformIO environments, and launchd or systemd services. It is especially useful as a reference design for local agent telemetry: narrow payload, explicit host-peripheral split, inspectable firmware, and physical controls that do not depend on the chat UI.

Skip it when your real problem is cost reporting, team governance, or audit-grade usage history. A physical meter will not replace account-level analytics. Also skip it when credential access is politically or technically hard to approve. In that environment, a software dashboard with read-only API tokens, central logs, or no HID device at all will be easier to defend.

For vibe-coding practice, the transferable idea is not the mascot screen. It is the pattern: move only the right telemetry across the boundary, keep credentials on the host, make the wire format inspectable, and write down the failure modes before the tool becomes part of your daily workflow.

Clawdmeter is worth publishing as a local telemetry boundary case study, not as a generic productivity gadget. Adopt it only when the credential, BLE, HID, firmware, and asset-licensing boundaries are acceptable.

Practical takeaway

Before using Clawdmeter, run a one-hour acceptance pass: flash the exact firmware/platformio.ini env, pair Claude Controller, verify launchctl list | grep claude-usage, tail the daemon log, confirm the JSON payload reaches RX ...0002, test Space and Shift+Tab focus behavior, and decide whether the Anthropic fonts/Clawd assets must be replaced.