VibePulse

A little always-on screen for your shelf that shows what your AI coding agents are doing — and taps you on the shoulder when one is stuck waiting for you.

Claude Code and Codex usage, live agent activity, and a full-screen NEEDS YOU alert. A ~$30 ESP32-S3 panel plus a pure-stdlib Python service on your Mac. No cloud, no accounts, no API keys on the device. Agent data never leaves your LAN; the optional public-repository module makes only anonymous GitHub API reads from the Mac.

The problem

When you run coding agents all day, two things are invisible:

• How much quota is left. You usually find out you're at the wall when a long task dies halfway through — not before you start it.
• When an agent stopped. It asks one yes/no question and then just sits there. You're in another window. Sometimes for twenty minutes.

Both answers already exist, buried in a terminal you're not looking at. VibePulse moves them onto a screen you can't miss: one glance from across the room, no window to switch to, no menu bar to squint at.

Status: work in progress. This is an ongoing project for me and plenty of tweaks are still on the list, but enough people asked about it that I'm opening it up now rather than when it feels "done". Expect rough edges and frequent commits.

What's on screen

Six core pages, swipe or auto-rotate, plus an optional seventh GitHub project page. Every image below is an exact 480×480 frame — the simulator renders the same pixels as the panel.

Usage — Claude's weekly and heaviest-model-weekly quota, plus Codex's weekly quota. Each with a reset countdown and how much you've burned today.

NEEDS YOU — when an agent blocks on your input, the whole screen turns into the alert, in that provider's colour, naming the project it's waiting on. Tap to dismiss.

Live agent monitor — the header shows which agents are working right now, with model and effort, on every page. 2 CHATS ACTIVE when several are running.

Burn rate — a forecast per provider: on pace, running out early (and when), or how much head-room is left at reset.

Max Tracker — a GitHub-style heatmap of your daily quota peaks, with coding streaks and max counters, per provider. Red cells are days you maxed out.

Both providers get equal treatment — same pages, same alert, their own accent colour:

Optional GitHub project pulse

One public owner/repository can add a deliberately sparse seventh page: the current star count is the hero and forks are the only secondary metric. The page and star moments are independent switches. A new star can therefore briefly take over the current VibePulse view even when the GitHub page is not in rotation. It covers the previous page with a quiet black stage, shows a large filled star, the repository, the stargazer when GitHub supplies one, the new total, and TAP TO DISMISS; otherwise it returns to the exact previous page after two minutes.

The Mac service polls GitHub's public API and republishes a small, validated LAN payload. The ESP32 never talks to GitHub, and a GitHub timeout or rate limit cannot stall the Claude/Codex endpoints. Configure it with:

python3 tools/tokenserver/tokenserver.py --github-repo owner/repository

Then opt into TK_GITHUB_SCREEN_ENABLED and/or TK_GITHUB_NOTIFICATIONS_ENABLED in your gitignored secrets.h. Both are off by default. No GitHub token is required for a public repository.

TK_GITHUB_SOUND_ENABLED is a separate default-off gate for the 258 ms A5-to-C#6 chime. The sequence and failure-isolated playback contract are in place, but the current target intentionally registers no codec backend until the physical speaker and display-DMA budget have passed device testing. A missing or failed sound backend never delays the popup or any network path.

It never makes numbers up

Before the first successful fetch, and whenever a source is missing, you get dashes — never a placeholder 0% that you might believe. If the service goes away, the last good numbers stay on screen and get marked stale rather than silently drifting.

Run Claude only, or Codex only, and the other half simply shows dashes.

Are you getting your money's worth?

The usage pages answer how much have I spent?. The value multiple answers the question you actually have every month: it prices the tokens your agents already logged at list API rates and divides by what you pay.

python3 tools/tokenserver/tokenserver.py --claude-plan max5x --plan-cost-usd 100

It counts cache tokens, which is the whole point — a real record here reads 2 input and 4 output against 23 655 cache-read, so pricing only input and output understates it by 577x.

Rates are not hand-maintained: they are generated from a public price catalogue by tools/tokenserver/update_prices.py and committed, so the server stays offline and refreshing is one command. An unknown model degrades the figure to a dash rather than being silently free.

How it works

        your Mac                             your shelf
┌────────────────────────────┐          ┌──────────────┐
│ ~/.claude/projects/*.jsonl │          │              │
│ ~/.codex/sessions/*.jsonl  │ ───────► │   ESP32-S3   │
│ rate-limit headers         │          │    AMOLED    │
└────────────────────────────┘          └──────────────┘
     tokenserver.py :8737           plain JSON over your LAN,
     pure Python stdlib                polled every 30 s

A tiny Python service on your Mac reads your local Claude Code / Codex logs and rate-limit headers, and serves plain numbers over your LAN. The screen polls it every 30 seconds. Your OAuth token never leaves the Mac; the screen only ever receives percentages, counts and coarse status.

What you need

• Waveshare ESP32-S3-Touch-AMOLED-2.16 (~$30). No soldering, just a USB-C cable. It's the same board Clawdmeter uses, so if you already own one you're 10 minutes away.
• A Mac on the same WiFi (the log-reading service is macOS-only for now)
• Claude Code and/or Codex. Either alone is fine.
• 2.4 GHz WiFi. The ESP32-S3 can't see 5 GHz networks.

Setup, the vibecoder way

Clone the repo, open your coding agent inside it (Claude Code, Codex, Cursor, whatever you run), and say:

Set up VibePulse for me: help me fill in secrets.h, build and flash the board over USB, and start the tokenserver on this Mac.

The repo is built for this. CLAUDE.md and AGENTS.md point your agent straight at docs/agent-setup.md — an English runbook written for agents, with a verification after every step, the traps that actually cost people an evening, and a symptom→fix table. That's the whole onboarding.

Reading rather than running? That runbook is also the fastest way to understand how the pieces fit together.

Setup, the manual way

1. Install ESP-IDF 5.5 and brew install cmake ninja

2. Clone this repo, then:

   cp secrets.h.example secrets.h   # fill in WiFi + your Mac's hostname (2 min)
   . ~/esp/esp-idf/export.sh
   idf.py set-target esp32s3
   idf.py build
   idf.py -p /dev/cu.usbmodem101 flash
   

   Don't miss this: in secrets.h, point the TK_VIBEPULSE_BASE_URL block at your Mac by replacing the DIN-MAC placeholder. Those URLs ship active on purpose — a wrong hostname is visible in the log, whereas an undefined URL compiles the fetch out entirely and the screen boots fine and shows dashes forever. Use your Mac's Bonjour name (scutil --get LocalHostName) rather than an IP, so the same firmware works on your home network and on a phone hotspot.

   Board not showing up under /dev/cu.usbmodem*? Hold BOOT, tap RESET, release BOOT and it re-enumerates in download mode.

   Power matters: flash with the board in download mode (screen dark). A computer USB port often cannot feed the running firmware. The AMOLED panel's draw makes the board bounce off the bus or hang, which looks like a flaky cable. After flashing, run the screen from its own USB power supply, not your computer.

3. Start the service on your Mac. Pure Python stdlib, nothing to install:

   python3 tools/tokenserver/tokenserver.py
   

   Autostart on login: see tools/tokenserver/README.md.

Over-the-air updates

After the first USB flash, the screen updates itself over WiFi. The consent chain is deliberate and three-fac