English | 简体中文
Your AI coding limits, at a glance.
QuotaFrame displays Codex and Claude usage percentages and quota reset countdowns on a dedicated desktop display.
QuotaFrame Bridge runs on your computer and syncs usage from CodexBar / Win-CodexBar over Bluetooth, keeping your quota status in view.
flowchart LR
A["CodexBar CLI"] --> B["Python Bridge<br/>Desktop"]
B -->|"Encrypted BLE / NUS<br/>usage.v1"| C["ESP32 Firmware"]
B -.->|"BLE / Folder Push OTA<br/>ota.folder.v1"| C
C --> E["Waveshare Boards with Displays"]
C --> D["Other Boards (e.g. M5StickS3)"]
The data source handles account sign-in and usage retrieval. Bridge sends only usage percentages, reset times, and sample timestamps to the device; it does not transmit account credentials. See the protocol documentation for the data fields.
| Device | Display | Key Features |
|---|---|---|
| Waveshare AMOLED 2.16 | 480×480 AMOLED | Touchscreen, clock screensaver, auto-rotation |
| M5StickS3 | 135×240 LCD | Button navigation, compact size |
| Waveshare ePaper 3.97 | 800×480 e-paper with four grayscale levels | Temperature and humidity, usage trends (microSD card required) |
| ESP-Mosaico | 480×480 AMOLED | Touchscreen, AI button, auto-rotation, camera gestures (experimental) |
| Waveshare RLCD 4.2 | 400×300 monochrome reflective LCD | KEY / BOOT navigation, clock, usage trends (microSD card required) |
| MindReset Read Pico | 684×1216 e-paper with 16 grayscale levels | Touchscreen and three keys, clock, auto-rotation, usage trends (microSD card required) |
All devices support Codex / Claude usage display, retain the last usage data when disconnected, and support firmware updates over Bluetooth. See the device guide for a full feature comparison and control shortcuts.
Open the web flasher in Chrome or Edge on your computer, select your device model, connect it via USB, and follow the instructions. No ESP-IDF installation is required.
For manual flashing or serial recovery, see the firmware guide.
| Platform | Data Source | Setup |
|---|---|---|
| Windows | Win-CodexBar CLI | Bridge downloads the CLI automatically if it is missing, or you can use a local installation. Your accounts must already be signed in. |
| macOS | CodexBar | Install the app and configure your accounts, then select Preferences → Advanced → Install CLI in the app. |
Download the package for your platform from Releases. No Python installation is required.
- Windows: Download and run
quotaframe-bridge-windows-v<version>-setup.exe, then follow the installation wizard. You can also run the portable.exedirectly. After launching Bridge, right-click its system tray icon to open the menu. - macOS (Apple Silicon only): Open the
.dmg, dragQuotaFrame Bridge.appinto Applications, and launch it. If macOS blocks the app, go to System Settings > Privacy & Security, click Open Anyway, and confirm Open. Right-click the menu bar icon to open the menu.
Select “Add Device” from the menu and follow the pairing instructions. On Windows, enter the six-digit pairing code shown on the device screen. On macOS, follow the system prompts. Bridge syncs usage automatically after pairing.
See the Bridge guide for installation and connection troubleshooting. You can start subsequent firmware updates from the Bridge menu; confirmation is required on both the computer and the device.
| Document | Contents |
|---|---|
| Device guide | Feature comparison, touchscreen settings, and control shortcuts |
| Bridge guide | Installation troubleshooting, pairing, configuration, and daily use |
| Firmware guide | Manual flashing, building from source, and firmware testing |
| Contributing guide | Getting started with development, testing, and contribution requirements |
| Open device access contract · Hardware porting | Third-party device integration and support for new boards |
| Roadmap and documentation index · Design guidelines | Development direction, technical documentation, and UI guidelines |
Thanks to Waveshare and MindReset for their support with development devices.
Usage data is provided by CodexBar and Win-CodexBar. Thanks to esp-desktop-buddy, LVGL, Bleak, pystray, Pillow, and PyObjC for supporting the firmware and desktop application.
The project code is licensed under MPL-2.0. See THIRD_PARTY_LICENSES.md for third-party components and their licenses.