People who use AI coding tools every day run into the same quiet worry: how much of my plan have I used, and when does it reset? The answer usually sits in a settings page or a command you have to type. Clawdmeter moves that answer onto a small round or square screen on your desk.
Clawdmeter is an open-source desk dashboard that shows Claude Code usage. It runs on Waveshare ESP32-S3 and ESP32-C6 boards with small AMOLED touch screens, and it pairs with your computer over Bluetooth. Its splash screen plays pixel-art animations of the Clawd mascot that get busier as your usage rate climbs. Two side buttons double as keyboard shortcuts. Other makers have built similar usage monitors for other tools, which shows how common the need is.
This article explains how Clawdmeter works, what you need and how to build your own version, for any tool that reports usage.
How it works in plain words
The board itself does not log in to anything. A small program on your computer, called a daemon, does that part.
The daemon reads the login token that Claude Code already stored on your computer. On macOS it comes from the Keychain. On Linux and Windows it comes from the Claude Code credentials file in your home folder.
About once a minute, the daemon makes a tiny API call, using a very small model and a single token. The usage numbers come back in the response headers, which report how much of the five-hour session and weekly limits you have used.
The daemon connects to the board over Bluetooth Low Energy and writes a short JSON message to it.
The firmware reads that message and updates the dashboard, which is drawn with the LVGL graphics library. It also tracks how fast your session percentage rises over a five-minute window and picks animations to match.
Separately, the two side buttons act as a Bluetooth keyboard. One sends Space, which can be used for push-to-talk in voice mode. The other sends Shift and Tab, which switches modes. These work directly with the paired computer and do not depend on the usage data.
The design is a good lesson. The secret stays on the computer. The board only receives numbers to display.
What you need
A supported board. The project supports several Waveshare boards, including the ESP32-S3-Touch-AMOLED-2.16, which was the original target, plus 1.8-inch and 2.06-inch AMOLED versions and an LCD version. Each board has its own folder in the firmware, and the shared code never sees board-specific details.
PlatformIO to build and flash the firmware.
Python 3 on the host computer for the daemon. Installers set up the daemon to start automatically, as a launch agent on macOS or a user service on Linux.
An active Claude Code login on the same computer.
Options in the installer let you choose a clock format and turn on a chime when your session limit resets, on boards with a speaker.
Building it step by step
Clone the repository and open the firmware folder.
Pick the build environment that matches your board and flash it with PlatformIO.
Hold the middle button to put the board in pairing mode, and pair it with your computer.
Run the installer for your operating system. It sets up the daemon and starts it.
Use Claude Code as usual and watch the screen update.
Building your own version with an AI coding tool
The bigger lesson here is the pattern: a host daemon gathers data, Bluetooth or Wi-Fi carries it, and a small board shows it. You can use that pattern for almost any number you check often.
The project itself includes a CLAUDE.md file that describes its structure, so an AI coding agent can find its way around. That is a good habit to copy. When you start your own version, write a short file that explains the board, the screen size, the pins and the data format. Then ask your agent to read it before each task.
A sensible plan for a first build:
Ask the agent to write the host script first. It should fetch the number you want and print it. Test it on its own.
Then ask for firmware that shows a fixed number on your screen. Get the display working before anything else.
Then add the link. Bluetooth is neat, but Wi-Fi with a small web request is often easier for a first project.
Finally, add animations, buttons and polish.
Pitfalls
Credentials. Any tool like this reads a login token from your computer. Read the daemon code before you install it, so you know exactly what it sends and where. Do not run a daemon from an unknown source with access to your accounts.
Terms of use. Polling an API for usage numbers is cheap, but check that it fits the service's rules, and keep the polling slow.
Bluetooth permissions. On macOS, the program that runs the daemon must be allowed to use Bluetooth. On Linux, the daemon may need extra permissions to open Bluetooth sockets. If the daemon hangs while scanning, permissions are the first thing to check.
Board revisions. The same board name can ship with different display or touch chips. Clawdmeter detects two revisions of one board at start-up. If your screen stays blank, check which panel your board has.
Variations
Show more than one plan at once. The installer can poll several configuration folders and show the active one.
Track a different tool. Some makers have built monitors for other coding assistants, and one commercial-style design shows quotas, session limits and token counts for several command-line tools on a four-inch screen.
Add build status, test results or deployment alerts from your own projects.
Use an e-ink screen for a version that only updates every few minutes and uses very little power.
The short version
Clawdmeter shows Claude Code usage on a small ESP32 AMOLED board. A daemon on your computer reads your existing login, makes a tiny API call, reads the usage headers and sends the numbers to the board over Bluetooth, while two buttons act as keyboard shortcuts. To build your own, copy the pattern, keep secrets on the computer, write a short project guide for your AI coding agent and build the host script, the display and the link one at a time.
Project resources: https://github.com/HermannBjorgvin/Clawdmeter