AI Monitor: an ESP32 touchscreen companion for Codex, Claude and more

Cato Rendal — Sat, 10 Oct 2026 03:12:04 +0000

AI Monitor puts supported AI account limits and locally recorded token activity on a small USB touchscreen. You can choose NOVA or ORBIT, two animated desk companions, and keep the usage dashboard visible while working on your main screen.

The project is open source, built with LVGL 9.6 and Arduino/PlatformIO, and now ships two separate firmware choices in the same repository and Windows package.

These images are renders of the actual LVGL interface with synthetic data, rather than photographs of the boards.

Watch the two-minute overview

Here is a short walkthrough of the project: NOVA and ORBIT, the LVGL screens, provider choices, quota windows, saved themes and the Windows host. It includes English narration, timed captions and chapters. The UI values are synthetic preview data, and the S3 port remains experimental.

Watch on YouTube.

Setup note: if more than one matching USB board is connected, select the display’s explicit COM port instead of auto, save settings, then start the host. The installed app keeps its own private configuration when moving from another folder.

Update: v1.17.2 — tested from erased P4 flash

A full uninstall-and-reinstall test found two real setup defects: the old P4 factory bootloader declared 4 MB rather than the board’s 16 MB, and Windows could select npm’s Unix Codex launcher. v1.17.2 fixes both. Do not use v1.17.0 for a new P4 installation. Existing application-only updates did not expose that bootloader defect.

The exact v1.17.2 CI installer was tested with an empty AI Monitor configuration and erased physical P4 flash. Board/providers/key/USB selection and First installation were completed through the GUI; the P4 booted without a manual repair and both Codex/ZCode quotas were received. 185 Python tests, both firmware builds, native LVGL checks and Windows install/upgrade/uninstall checks passed. Factory capacity and partition validation now run before packaging and flashing.

Windows binaries remain unsigned, so SmartScreen may warn. Microsoft’s earlier-file submission is not approval of this different installer. S3 remains experimental and physically untested; advanced bridge requirements are unchanged.

Download the corrected v1.17.2 installer and portable package

Previous update: v1.17.0 — guided AI setup and verified host health

The new Windows AI setup tab has provider checks, Codex install/sign-in and an optional Claude quota link that can be removed without replacing a custom statusline. OpenCode now reads supported local numeric usage automatically; Copilot, Cursor and Antigravity still require an advanced numeric bridge.

Host settings adds USB retry, local token polling, terminal text size and start/close preferences. Process status, verified USB identity and quota readiness are shown separately. The firmware Settings help reflects the provider changes.

176 Python tests, both firmware builds, native LVGL checks and packaged Windows installation/upgrade/uninstall checks passed. I also used the exact release installer and application update on my physical P4, preserving settings and confirming live Codex/ZCode quota readiness. S3 remains experimental and physically untested.

The installer is still unsigned. The exact file was submitted to Microsoft for review; the decision is pending and SmartScreen may still warn. No Windows protections are disabled.

Download v1.17.2: installer, portable ZIP and SHA-256 checksums

Previous update: v1.16.1 — explain the quota, test the installation

The display now explains usage through SET > AI USAGE. Each option shows the remaining percentage and whether the data is reported, missing, stale, updating, offline or in error. The choice is saved per provider and applies to both NOVA and ORBIT.

Codex: 5 HOURS is the short-term limit; 7 DAYS is the weekly limit. The page points users to ChatGPT sign-in in the PC app.
ZCode: 5 HOURS / 7 DAYS are model quotas when reported; MONTHLY MCP is a separate tool-call allowance. The page explains the user's own ZAI Coding Plan key. Monthly MCP is not a monthly token budget. The host now includes the monthly MCP row and stops labeling weekly model usage as monthly.
Claude Code: reported quotas need the optional statusline bridge. Gemini CLI: recorded activity only. Other editors require a numeric bridge rather than automatic account import.

Actual LVGL UI renders with synthetic values, not photographs.

A known missing window can be selected in advance, but its percentage stays unavailable until real data arrives. Live values update while Settings is open; option identities remain stable during touches. REFRESH explicitly reloads the available rows. Alerts still monitor every window, independent of the one chosen for the companion display.

One installer, guided provider setup

Run AI-Monitor-Setup-v1.16.1-windows.exe to install the full Qt app, runtime, flasher and both firmware choices for your Windows user. No separate Python/PlatformIO installation or administrator access is required. You still choose your own board/providers and supply your own account or key; neither an AI nor a board is preselected.

The Windows app has NOVA artwork, instructions for all eight AI choices, a masked key field, and persistent firmware progress/error messages. First installation requires checking the USB target and typing FLASH; application updates verify the existing display identity. Double-clicking the command-line flasher explains its role and offers to open the graphical Firmware tab. Closing the app after Start host succeeds leaves the independent host running in the background.

The wider AI column retains 40-pixel percentages, 20-pixel provider names and 16-pixel status text. Notifications have a 136-pixel banner, 24-pixel heading, 20-pixel body and a 60-pixel dismiss target.

Verify the delivered binaries

Validation includes 148 Python tests, native LVGL/protocol tests for both profiles, NVS checks, both firmware builds and exact packaged GUI/flasher startup. Windows smoke tests cover a clean installation, upgrade and uninstall while preserving private settings. The P4 application update and stable boot were also verified on the physical board.

Limits remain explicit: the original Waveshare S3 is experimental and untested on physical S3 hardware. The Windows apps remain unsigned, so SmartScreen may warn; installing them does not disable Windows protection. Tested setup is not a guarantee for every Windows policy or hardware combination.

Download v1.16.1: installer, portable ZIP and SHA-256 checksums.

What the robot actually follows

The robot reacts to increases in recorded token counters. Quota polling is a separate signal: fetching an account limit does not make the robot look busy.

The first counter sample establishes a baseline. Some clients write their usage only after a request finishes, so animation can lag generation. This is an activity display, not a billing ledger or a per-token stream.

Local activity adapters cover Codex, ZCode, Claude Code, Gemini CLI and supported OpenCode SQLite schemas. Codex uses the signed-in official CLI for supported account quota, ZCode can use an optional Z.AI coding-plan key, and Claude quota can use its documented statusline bridge. Gemini supplies recorded activity only. Other selectable providers require an external numeric telemetry bridge; selecting a name does not automatically connect its editor.

The interface

Besides the companion view, the screen has:

A provider dashboard and individual quota windows.
Reset countdowns, manual refresh and low/critical quota warnings.
Session history and last-valid values during temporary provider failures.
Two robots and four saved color themes: Forest, Ocean, Amethyst and Ember.
Brightness presets, idle fades and a night schedule.

Two boards, different display backends

The original target is the GUITION JC4880P433 ESP32-P4, with a ST7701S MIPI DSI display and GT911 touch. Its portrait panel is rotated into an 800 × 480 landscape UI, and brightness uses hardware PWM.

Version v1.13.0 adds the original Waveshare ESP32-S3-Touch-LCD-4.3 as a separate, experimental target. That board uses a native 800 × 480 ST7262 RGB panel, GT911 touch, a CH422G expander, 16 MB flash and 8 MB OPI PSRAM. The B/C variants are not supported.

The S3 firmware has not been tested on physical hardware. It compiles and the shared native tests pass, but touch alignment, RGB stability, tearing and sustained operation still need a real board test.

A useful hardware lesson from this port: similar-looking screens need different brightness handling. The original S3 board exposes an LED on/off switch, so intermediate brightness dims the rendered image with a touch-transparent overlay. Only zero switches the LEDs off. It does not reduce LED power like the P4's PWM.

Keeping the UI shared

Both boards share the dashboard, robot artwork, themes and protocol. Their drivers stay separate. LVGL and backlight changes belong to one UI task, while the host communicates through bounded AIM1/JSON frames.

The S3 backend uses one PSRAM framebuffer, RGB bounce buffers and a partial LVGL draw buffer to fit its smaller memory budget. Its Arduino core and matching Espressif PSRAM XIP SDK are pinned separately from P4. A single RGB framebuffer can still show tearing; passing a build is not a substitute for observing the hardware.

CI builds both targets, and the project has 176 synthetic Python tests, protocol checks for both board identities, NVS settings tests and tests of the actual LVGL screens under both profiles.

Try it

The GitHub repository contains source, screenshots and setup instructions. The v1.17.2 Windows release includes the host runtime, firmware flasher and both firmware variants, so users do not need Python or PlatformIO installed.

Extract the whole ZIP, open AI-Monitor.exe, choose your exact board and AI providers in First-time setup, and install the matching firmware. Fresh installations have neither a board nor an AI provider preselected. S3 uses its USB TO UART connector for flashing and everyday host data.

The PC companion reads selected usage sources and sends display data over USB. Provider credentials stay on the PC; no maintainer keys are distributed. Project-owned code and robot artwork use MIT, while bundled components and provider marks retain their own terms. The USB protocol builds on tobymarks/esp32-ai-monitor.

I'd welcome feedback on the interface and, especially, hardware testing from anyone with the original Waveshare S3 board. The board guide in the repository lists the remaining checks.

DEV Community: Cato Rendal