ESP32 Desk Display for Claude and ChatGPT Usage Limits

Why I built this

If you work with Claude, ChatGPT, Copilot or Cursor all day, the usage limit tends to show up at the worst possible moment: halfway through a refactor, or right before a demo. The numbers exist, but they are buried in a settings page or a menu bar popover you never look at.

I wanted them where I actually look: on the desk, next to the keyboard, always on. The ESP32-2432S028R, better known as the "Cheap Yellow Display" (CYD), turned out to be a perfect fit. It is inexpensive, has a 2.8-inch color touchscreen and USB on board, and needs no soldering at all.

What it does

AI Monitor shows the current limits of one provider at a time: Claude, ChatGPT, Gemini CLI, GitHub Copilot, Cursor or Antigravity.

• Session and weekly limits (and provider-specific rows where available) as rings or bars
• Live countdown until each limit resets
• Used or remaining percentage, whichever you prefer
• Portrait and landscape layouts, light and dark themes, adjustable brightness, language and timezone
• A standby clock when the computer is asleep or the app is closed

How it works

AI providers -> CodexBar CLI -> AI Monitor app (macOS / Windows) -> USB serial -> ESP32 CYD

The display does not talk to any AI service, and it never sees an API key or login. All of that stays on your computer:

• CodexBar is an open-source tool by Peter Steinberger that reads your usage limits locally. Its CLI returns them as JSON (codexbar usage --provider claude --json). On Windows, Win-CodexBar provides the same CLI.
• The AI Monitor companion app calls that CLI every three minutes, applies your display settings and builds a compact JSON frame.
• USB serial carries the frame to the ESP32 at 115200 baud. The usage data travels only over this cable.
• The firmware parses the frame and renders it with LVGL.

A trimmed example of a frame:

{
  "schemaVersion": 1,
  "frameId": 42,
  "displayTime": "15:30",
  "data": [{
    "provider": "claude",
    "usage": {
      "rows": [
        {"title": "Session", "usedPercent": 37, "resetsAt": "2026-09-10T17:00:00Z"},
        {"title": "Weekly",  "usedPercent": 62, "resetsAt": "2026-09-14T09:00:00Z"}
      ]
    }
  }]
}

The ESP32 answers every frame with a short acknowledgement:

{"type":"ack","frameId":42,"message":"accepted","provider":"CLAUDE","rows":3}

Step 1: Get the board

Buy an ESP32-2432S028R. Two panel variants are sold under almost the same name: most boards use an ILI9341 controller, some use an ST7789. You don't need to know which one you have in advance, the app handles both.

Step 2: Install CodexBar

• macOS: install CodexBar from https://codexbar.app or with Homebrew: brew install --cask steipete/tap/codexbar
• Windows: install Win-CodexBar with winget install Finesssee.Win-CodexBar

Then enable the providers you use (Claude, ChatGPT, Copilot, …) in CodexBar and make sure they show data there.

Step 3: Install the AI Monitor app

Download the app from https://github.com/tobymarks/esp32-ai-monitor/releases:

• macOS: the app-v* release (AIMonitor.dmg), a universal binary that is signed and notarized
• Windows: the win-v* release (AIMonitor-Setup.exe). This is a beta: it has not been tried on real Windows hardware yet, and the installer is not code-signed yet, so SmartScreen warns on first launch

On Windows you may need the driver for the CH340 USB-serial chip if Windows does not install it automatically.

Step 4: Flash the firmware

Connect the CYD with a USB data cable. Open the app's settings, choose Flash firmware and pick the board variant:

• Standard (ILI9341): ESP32-2432S028R, try this first
• Alternative (ST7789): ESP32-2432S028

The app downloads the matching firmware from GitHub Releases, erases the flash, writes and verifies it. No PlatformIO, esptool or Arduino IDE needed. If the screen stays white or shows noise afterwards, flash the other variant.

Step 5: Pick a provider

Choose the provider in the app. The app detects the display on USB automatically, and whenever you plug it in, it immediately resends the current values. From then on the display updates on its own.

An optional quick menu in the menu bar lets you switch providers without opening the settings.

Step 6 (optional): Print a case

The CYD fits existing 3D-printable enclosures. I use these two from MakerWorld:

• Landscape: Weather Station Pro for ESP32-2432S028 CYD – https://makerworld.com/de/models/2583102
• Portrait: Aura Smart Weather Forecast Display – https://makerworld.com/de/models/1382304

Under the hood

Firmware. Built with PlatformIO on Arduino-ESP32, with TFT_eSPI for the panel, LVGL v9 for the UI and ArduinoJson for parsing. There are two build targets, esp32dev (ILI9341) and esp32dev-st7789. The UI adapts to up to three usage rows per provider.

Serial protocol. The app opens the port, sends {"cmd":"get_info"} and waits for the firmware to report its version and maximum frame size. Short commands such as brightness or orientation go as single JSON lines. Usage frames go with a small length-prefixed header (AIM1 <bytes> <frameId>), so the ESP32 knows exactly how many bytes to read, and each frame is acknowledged. If data gets stale, the display shows it instead of pretending the numbers are current.

Companion apps. The Mac app is written in Swift and AppKit with plain POSIX serial I/O. The Windows app uses Tauri 2 with a Rust backend (serialport for the link, espflash for flashing) and a React frontend. Both check GitHub Releases for app and firmware updates and remember settings per display.

Optional Wi-Fi. Usage data never uses Wi-Fi. If you want the standby clock to stay accurate while the computer is off, you can give the display Wi-Fi credentials; it then only syncs the time via NTP.

Build it yourself

# Firmware
pio run -e esp32dev -t upload          # ILI9341
pio run -e esp32dev-st7789 -t upload   # ST7789

# Mac app
cd companion && ./build.sh

# Windows app
cd companion-windows && pnpm install && cargo tauri dev

The full USB serial protocol is documented in the repository, so you can also feed the display from your own scripts.

Credits

• CodexBar by Peter Steinberger, which does the hard part of reading the usage limits: https://github.com/steipete/CodexBar
• Win-CodexBar, the Windows port of the CLI: https://github.com/nesszer/Win-CodexBar
• Brian Lough and the CYD community for documenting the board: https://github.com/witnessmenow/ESP32-Cheap-Yellow-Display
• The authors of the two MakerWorld enclosures linked above

Everything in this project, firmware, both apps and the website, is open source under the MIT license.