| name | dev |
| description | Boot and drive the tbh-meter app + reader locally to see a change working — what runs on macOS (UI only; the reader is win32-only) and how to feed the overlay/list fake data. Use when asked to run/start the meter, verify a change in the running app, screenshot the overlay, or reproduce a bug locally. |
Running tbh-meter locally
The app (Electron overlay) — macOS runs UI only
cd app && pnpm dev
On macOS the reader never spawns, but the file-watching sources still work — drive the UI by writing
artifacts into ~/tbh-meter/:
raw/<endTsMs>.json — a finished run. The converter turns it into logs/<id>.json and the list updates.live.json — the overlay snapshot. Rewrite it with an ADVANCING mtime each tick, or the overlay
won't animate (engagement detection keys off mtime).
Steal real fixtures from app/src/main/**/__tests__/ or a teammate's ~/tbh-meter/. RC build uses
~/tbh-meter-rc/ instead.
Screenshot the overlay/list (CDP)
Renderer changes must be verified on real pixels, not just unit tests (app/CLAUDE.md). Launch with
the debugger open and drive it over CDP:
cd app && pnpm dev -- --remote-debugging-port=9222
Then connect a CDP client to localhost:9222 and capture the window against the seeded ~/tbh-meter/
artifacts above.
The reader (Python) — Windows only
The reader reads game memory and only runs on win32 (reader/CLAUDE.md). On macOS you can lint and
test it but not attach to the game:
cd reader && ruff check . && python3 -m pytest
Verify before finishing
cd app && pnpm check && pnpm test
cd reader && ruff check . && python3 -m pytest
