vibepulse
A shelf-top AMOLED screen showing your Claude Code & Codex usage, live agent activity, and a NEEDS YOU alert when an agent waits for your input. ESP32-S3 + a pure-stdlib Mac service. Nothing leaves your LAN.
What is it?
What it is
A hardware-software system displaying real-time AI agent activity, quota tracking, and interactive alerts on an ESP32-S3 AMOLED panel, with optional encrypted cross-network communication.
Why it exists
To make AI coding agent status and resource usage visible at a glance, preventing missed agent prompts and quota exhaustion through persistent visual feedback and tap-based interaction.
Who should use it
Developers running AI coding agents (e.g., Claude Code, Codex) who want a physical display for quota and agent status and are comfortable flashing an ESP32‑S3 board and running a local Python tokenserver.\n"who_should_avoid":
Who should avoid it
Teams that need a fully managed SaaS with enterprise SLAs out of the box.
How it works
A quick walkthrough in plain English
How vibepulse works
Step 1 of 3
You interact with it
Open vibepulse, send a request, or connect it to your stack.
Features
Advantages
- Gives visibility into invisible quota usage, preventing surprise at the wall
- Alerts you when an agent is waiting for input, reducing idle time and context switching
- Physical tap interface lets you answer questions without switching windows
- Low‑cost hardware (~$30) provides powerful insight into AI‑coding activity
- Simple setup via coding agents (Claude Code, Codex) or manual steps
- No internet needed for core functionality – all data stays on your LAN
- OTA updates with physical confirmation keep firmware current safely
- Independent switches give fine‑grained control; no feature is silently enabled
- Simulator allows development and testing without the physical board
- Real‑time data from local logs; no cloud dependency or OAuth token leakage
- Always‑on screen is visible from across the room, no window to minimize
- Supports both Claude and Codex equally with distinct accent colors
- Accurate cost tracking includes cache tokens, avoiding under‑estimation
- Portable network switching works with phone hotspots, follows you anywhere
- Open‑source and extensible via the Torget app platform
- Clear, honest UI – dashes instead of invented zeros, no misleading placeholders
- Physical button interactions reduce cognitive load and keep you in flow
Disadvantages
- Requires a specific Waveshare ESP32‑S3‑Touch‑AMOLED‑2.16 panel (~$30); not generic hardware
- Claude quota reading is macOS‑only for now; Linux/Windows support is limited
- Only 2.4 GHz WiFi is supported – cannot connect to 5 GHz networks
- Setup involves multiple steps (flashing firmware, configuring secrets.h, starting tokenserver) that can be complex for non‑technical users
- The board needs its own USB power; computer USB may not supply enough for the AMOLED panel
- OTA updates require a physical 3‑second KEY3 hold, which can be inconvenient
- Interaction relay and numbers relay are optional and add extra configuration if you need remote access
- GitHub module reads the public API; rate limits or downtime could affect the pulse (though cached)
- Simulator requires SDL2, CMake, and a build environment – not as lightweight as the hardware
- Limited to Claude and Codex; other providers (Cursor, Gemini CLI, etc.) are not supported
- Captive portals, guest networks with client isolation, and WPA2‑Enterprise are not supported
- Panel can remember only up to six WiFi networks – more locations require manual re‑teaching
- If the tokenserver stops, the screen shows stale data; no real‑time updates until it resumes
- Flashing the board requires entering download mode (hold BOOT, tap RESET) – can be fiddly
- UI is locked to 480×480; porting to other displays would need layout and font adjustments
- The project is work‑in‑progress; frequent commits and rough edges are expected
- A lost or stolen screen leaks WiFi credentials and the Mac’s hostname – you must rotate both manually
Installation
native
python3 tools/tokenserver/tokenserver.py --github-repo owner/repository
FAQ
What hardware do I need to build VibePulse?
You need a Waveshare ESP32-S3-Touch-AMOLED-2.16 panel (~$30) and a USB-C cable. No soldering required. The same board is used by Clawdmeter, so if you already own one you can reuse it.
Can I run the tokenserver on Windows or Linux?
Windows is fully supported for the tokenserver. Linux is not yet supported (see issue #2), but contributions are welcome. The tokenserver is pure Python stdlib with no external dependencies.
Does VibePulse require an internet connection?
No. By default, the panel only talks to the tokenserver on your local LAN. Internet is only needed if you opt in to the optional numbers relay or encrypted interaction relay for cross-WiFi access.
Can I use VibePulse with only Claude Code or only Codex?
Yes. If you run only one provider, the other half of the UI simply shows dashes instead of zeros. Both providers get equal treatment with their own accent colours and pages.
How do I update the firmware after the initial USB flash?
Over-the-air updates are built in. Hold KEY3 for 3 seconds to open a 10-minute maintenance window, then run `tools/ota-flash.sh <device-ip>` from your computer. The device verifies the image, writes to the inactive A/B slot, and rolls back automatically if the new firmware fails a 15-second boot-health check.
How does the WiFi setup work when I take the panel to a new location?
The panel remembers up to six networks. At a new location, hold KEY3 for 3 seconds (or wait 90 seconds without a network) to open a setup window. Run `tools/wifi-here.sh` on your Mac to securely transfer the current WiFi credentials via the panel's access point, or join the 'VibePulse-setup' network from your phone and enter credentials through the captive portal.
Featured in Videos
YouTube tutorials and walkthroughs for vibepulse
Alternatives
Similar projects ranked by category, topics, and text overlap.
