yoyū — Japanese for room to spare. A tiny desk gadget that shows your Claude usage limits at a glance — how much you have left in each window, when it resets, and a phone alert when you're running low. No terminal, no menubar, no estimating.
Built on one ~$26 Waveshare ESP32-S3-Touch-LCD-2 — screen, touch, battery header and USB-C all on it. No Raspberry Pi, no Linux, no soldering. A second, larger board is supported too — see Buy the hardware.
Meters · Focus · the kitsune, down to one tail — tap to cycle
The kitsune is one of five characters; the others are a moon, a candle, a plant and a cat.
The board shows Claude Code's usage limits, and it gets them by reading Claude Code's own login — there's no API key to paste and no account to create. So it needs, on the computer you set it up from:
- Claude Code installed and signed in. Claude Code comes with the paid Claude plans (Pro and Max) and isn't part of the free tier — so a free account leaves the board with no login to read.
- One pairing, once. After that the board reads your usage on its own over Wi-Fi and tops itself up from your computer whenever that's on. Switch the computer off for more than a few hours and the board pauses until you're back — it's handed a short-lived token it deliberately can't renew, so that it can never sign you out of Claude Code. (Pairing hands it that login, so Claude Code has to be signed in first.)
If claude runs on your machine and you're signed in, you're good.
Two boards work. Both flash from the browser — the setup page asks which one you have before it writes anything, because the image and the panel have to match.
Waveshare ESP32-S3-Touch-LCD-2 — 2", 240×320, about $26. The reference board: every screen is drawn against this panel first, and touch works. on Amazon · direct from Waveshare
Waveshare ESP32-S3-Touch-AMOLED-2.16 — 2.16", 480×480, square. Brighter, and true black rather than backlit, so it starts on the dimmer theme and draws the same layout bigger rather than fitting more in. It boots, joins Wi-Fi, shows every screen and reads your usage.
Touch does not work on the unit I have. The screen is a display, not a control: screens rotate on their own and everything else is configured from a browser, but you cannot tap it.
This is not a Yoyu bug. Waveshare's own driver, built from their own example library and run on the same board with their own pin definitions, behaves identically — no touch reported, and the controller's interrupt line never asserts once across 40 seconds of pressing. An interrupt is the controller's own response to detecting a finger and happens before any driver reads a register, so the controller is not sensing the panel at all. Every software check passes: right part (
0x9220), real firmware, valid check code, correct resolution, mode unlock confirmed.The schematic rules out the wiring. Display and touch share one 24-pin FPC at
J40, the display works through it, and the touch controller answers on I²C through it — so the connector is seated and conducting. Neither the CST9220 nor the CO5300 is on the mainboard schematic, so both are bonded to the panel module. The dead link is between the controller and the sensing grid, inside that module. It is a faulty panel, not a repair and not a driver change. Details
As an Amazon Associate I earn from qualifying purchases.
No tools, no command line:
- Flash it in your browser. Open https://daveeuson.github.io/Yoyu/ in Chrome or Edge, pick which board you have, plug it in over USB-C, and click Connect & Install.
- Set Wi-Fi in the same window — it hands the board your network over the same USB cable (Improv). No hotspot, no typing an address.
- See your usage. Download the companion app from that page and open it — it finds the board on your network and feeds it your real usage. Or make the board self-contained (below).
Both boards on one network is a supported setup, not a workaround. The companion finds every board and feeds them all from a single read of your usage, and the tray gives each one its own submenu.
Two things are per board rather than shared: pairing (each holds its own
top-up key, so pair each one you want to run without this computer) and
yoyu.local, which only ever names one of them — the second board to
start comes up as yoyu-2.local, and that assignment swaps when they reboot
together. Each board prints its own permanent id at the bottom of the
page it serves at its own address.
If you add a second board later, run --rescan or use the tray's Look for
boards — nothing goes looking again on its own while a saved board is still
answering.
Pairing a board takes one click; so does undoing it. Disconnect from Claude
sits in the companion's tray menu beside Pair board, and on the board's own
/settings page. It clears the login and revokes the key your computer uses to
top the board up — Wi-Fi, theme, character, screens and history all stay. From
the command line: companion.py --disconnect.
- Companion app (easiest). A small app on the computer where you use Claude
Code. It reuses your existing Claude login to read your real numbers — the
same ones
claude /usageshows — and pushes them to the board. Double-click and forget: it auto-finds the board and starts with your computer. (It never does a fresh sign-in, so it avoids the throttle that blocks third-party logins.) - Self-contained (no computer). Run the companion once with
--pair; the board shows a short confirmation code on its screen, you type it in, and only then does it take your login — so the token goes to the physical device in front of you, not to whatever answered first on the network. The board then polls Anthropic directly and refreshes its own token — nothing runs on your computer afterward.
- Meters for every usage window Claude reports (5-hour session, weekly, weekly Opus…), fuel-gauge style — amber under 30% left, red under 10%.
- Reset countdowns and a clock.
- Usage credits, once you go past your plan limits and start spending them — the money where the percentage goes, and a phone alert the first time a period tips over. It only appears when credits are actually being spent; having them available is a fact about your account, not about today.
- Eight screens, cycled by a tap or on a timer: meters, focus, history, your character, a timer, actions, projects and settings — each one can be switched off if you don't want it in the rotation.
- Five characters, and each is a gauge rather than a decoration — it shows how much headroom is left in its own way. The kitsune fans out one to three tails; the moon waxes through its phase; the candle burns down; the plant grows; the cat gets a bigger ball of yarn. Four of the five are continuous, so 47% looks like 47% instead of rounding into a bucket. Pick one on the board's settings page.
- Six themes — Night, Dim, Paper, Mono, Nord and Tokyo Night, set from the board's own settings page.
- Touch & motion — tap to cycle screens, long-press to flip % left / % used, swipe for brightness; flip it face-down to sleep, shake to wake. (2" LCD board only — touch is not working on the AMOLED yet.)
- Battery gauge from the LiPo header.
- Phone alerts via ntfy or Pushover when a window crosses a threshold, with a recovery notice — plus one the first time a period starts spending usage credits, and one if the spend limit is reached. Those two aren't tied to the percentage: the useful moment is the first cent, whatever the cap is.
- A tray icon that matches your board — whichever of the five characters you picked, tinted green while it's feeding and red when it's stuck.
- Verified TLS — every connection to Anthropic, GitHub, and the alert
providers checks certificates against a pinned set of root CAs (no
setInsecure()), so a network attacker can't intercept your Claude token or spoof a response. - Signed updates — OTA images are verified against a public key baked into the firmware before flashing; an unsigned or tampered image is refused and the board stays on its known-good version.
- Confirmed pairing — handing the board your login requires a one-time code shown on its screen, so the token only ever goes to the physical device in front of you — not to whatever won the network discovery race.
Designed for a trusted home or office network. Details and threat model in
docs/HARDENING.md.
Full guide: docs/TROUBLESHOOTING.md. The common ones:
- "Waiting for your computer" — normal. The board's access token has run out and only the companion can mint another; open it (or just log in, if it starts at login) and the board catches up within a couple of minutes.
- "Login expired – re-pair" — firmware older than v1.6.3 signed itself in
and rotated the token your computer was using, logging one of you out about
once a day. Update the board at
/update, then pair once more; it can't happen after that. - "Couldn't reach the board" / 404, or no pairing code — usually two devices
answering to
yoyu.local(e.g. an old Pi still running). Turn off the one you're not using, or point the companion straight at the board with--pi http://<board-ip>:8080. - "Rate limited" — more than one device polling the same account. Leave one running and wait out the countdown.
firmware/— the ESP32 firmware (PlatformIO). Board pinout, day-1 runbook, and roadmap infirmware/README.md.companion/— the desktop app that feeds the board. Seecompanion/README.md.docs/— the browser-flasher setup page (served by GitHub Pages), the troubleshooting guide, and the release checklist (docs/RELEASE.md).
Buyers never need this — they use the browser flasher above. To change the
firmware: install VS Code + the PlatformIO
extension, open the firmware/ folder, and hit Upload. Full runbook in
firmware/README.md.
The original, deluxe build — a Raspberry Pi Zero 2 W with a full web dashboard and the "Pip" mascot — lives in its own repo, YoyuZero. This repo is the self-contained ESP32 appliance.
MIT — see LICENSE. Made by Dave Euson with love in San Diego.
© 2026 Dave Euson.