What is claude-usage-epaper?

This project shows your Claude Code usage numbers on a small 2.9-inch e-paper display. The display has bars for session limits, weekly limits, and per-model limits, with reset times under each bar. The idea is to put your usage information in one physical place without taking up any screen space on your computer. Because Home Assistant polls the numbers and pushes them to the panel, the display keeps updating even when your computer is off. Phone and web usage count against the same limits, so the numbers stay correct regardless of which device you used. The hardware is a FireBeetle 2 ESP32-C6 board connected to a Waveshare 2.9-inch e-paper module, powered over USB. Any ESP32 board that ESPHome supports would work with some pin adjustments. A 3D-printed stand holds the display, and the repository links to the stand model. Wiring details are provided to match the configuration in the code. Home Assistant polls an Anthropic API endpoint every five minutes, reads the usage data, and exposes it as sensors. The ESP32 subscribes to those sensors and draws the bars on the e-paper panel. The display only redraws when something actually changes, so it is not flashing all day. Any bar at 80 percent or higher flips to white-on-black for readability across a room. If authentication fails, the panel shows a full-screen banner rather than stale or made-up numbers. Setup involves four steps. First, you run a Python script to mint an OAuth token by opening a URL, authorizing, and pasting a code back. Second, you add configuration files to Home Assistant and paste the token into a helper field. Third, you set up the ESPHome device with its configuration and flash it over USB. Fourth, you configure an auto-renewal script so the token refreshes itself every four hours, meaning you do not have to touch it after setup. The repository includes the scripts and YAML files for all of these steps. The usage endpoint is unofficial, so Anthropic could change or break it at any time. If the response format changes, the display falls back to showing dashes rather than wrong numbers. The repository notes that the token and credentials grant account access, so backup encryption is recommended and re-minting is the fix if anything leaks. The full README is longer than what was shown.