-
-
Most Twitch tools watch the chat. Spotter watches the streamer.
-
Tag Out: one click starts a real Twitch raid, confirmed by EventSub.
-
Observations from the model. Decisions from tested code.
-
QR Guard: test QR in 93/538 recorded OBS frames without protection, 0/539 with it.
-
Chat Guard on real Twitch chat: a private term is held by AutoMod before it posts.
-
Pre-stream check: red blocks, amber asks, green goes. Read-only on OBS.
-
Built with Codex: our real Codex thread, npm test 181/181 and git log.
-
Real Twitch: score crosses 80, and seconds later the viewer's player shows the privacy scene. Stream marker accepted.
On October 28, 2026, an IRL streamer's chat spotted the ordering QR code on his restaurant table, and strangers started placing orders on stream. Spotter is the guardian that covers you before that happens.
Video: https://youtu.be/iL9hpO167Rc
At a glance (video: 0:41 viewer-side privacy · 0:49 AutoMod · 0:58 QR Guard · 1:41 real raid · 1:48 Codex):
- Real Twitch: real vision crossed 80 → the viewer's Twitch player switched to the privacy scene and Twitch accepted a stream marker; AutoMod held a private term; a full two-channel raid round trip, EventSub-confirmed.
- QR Guard: a local detector covered a test QR in milliseconds: it appeared in 0 of 539 recorded OBS program frames with protection vs 93 of 538 without.
- Built with Codex: one Codex thread, 49 commits, 181 tests passing, live bugs turned into regression tests first.
Inspiration
A QR code. A bus number. A shop awning. A reflection in a window. On their own, they're nothing. Added up across a few minutes of an IRL stream, they're how chat finds a streamer. IRL is one of the fastest-growing parts of Twitch, and TwitchCon itself has had to add no-filming zones and stricter rules around it.
At the same time, streaming is exhausting. In one study by Healthy Gamer and Stream Hatchet, 69% of creators reported burnout, and a tired streamer notices less of what's around them.
We wanted a tool that looks after the person on camera, not just the chat.
What it does
Spotter is one guardian for one moment every IRL streamer knows: you might be findable, you're getting tired, and you need someone to cover for you. It runs locally next to OBS and Twitch, and every part follows one rule: observations from the model, decisions from tested code.
Core: Off the Map and QR Guard keep you hard to find. Second Wind and Tag Out extend the same loop: when you're low on energy and exposed, Spotter tells you to move or take a break, and hands your viewers to a friend.
01 · Off the Map: stay hard to find
- Every 4 s Spotter samples the OBS program output and asks an OpenAI vision model for identifying clue categories only: a storefront, a transit identifier, a building number, a reflection.
- The model never names a place and never transcribes text. The structured-output schema has no location, address or text field, and a test fails if one is ever added.
- Pure, tested code adds clues up over time into a private 0–100 findability score. At 80, Spotter switches OBS to a privacy scene and creates a Twitch stream marker. One click restores the exact previous scene.
- QR Guard: some things can't wait for a score. A local, geometry-only detector checks the program output every 150 ms; a 500 ms OBS render delay gives it look-ahead, so the code is covered before that frame is encoded. The QR payload is never decoded or stored.
- Pre-stream check: before you go live, Spotter reads your OBS setup and blocks (red) on screen or window capture, the private dashboard as a source, or a missing privacy scene; it flags (amber) clues or QR codes in frame.
- Chat Guard: your private terms go to Twitch Blocked Terms, so AutoMod holds them before they post. Messages that try to guess where you are are flagged for your mods with an ID-only log; auto-delete is opt-in.
02 · Second Wind: keep some in the tank
- A browser sensor reads the microphone locally. Raw audio never leaves the browser; only numeric features do (loudness, pitch, spectral slope, voicing, pauses, speech rate).
- Energy is scored against your own baseline, never as a health measurement. Optional public stamina HUD and a chat "rally" meter.
- Tired + exposed: when energy stays low while findability is high, Spotter says it plainly: move, or take a break.
03 · Tag Out: nobody streams alone
- A small crew shares only live status and energy level. When you're low, Spotter suggests a crew member who is live with energy to spare. One click starts a real Twitch raid (Helix), confirmed by EventSub.
- The partner's overlay shows "Covering for your community". When you're back, the partner approves the tag-back raid home.
Works on any Twitch channel: our test accounts are neither Affiliate nor Partner.
How we used Codex
Don't take our word for it — open the repo:
- One Codex thread built the product, phase by phase, from a brief, a phased plan and an
AGENTS.mdwith hard rules (session ID01a1870e-38d9-7811-a561-bbb087422115). 49 commits;npm test: 181 pass, 0 fail. The README starts with a 2-minute "For judges" section. - The rules shaped the code: decisions only in pure functions under
src/core/with unit tests; no Twitch, OBS or model calls outside their adapters; never produce or store a location; anything simulated carriessimulated: trueand a visible badge. A core-purity regression test enforces the boundary. - Tests first, and live failures became regressions before fixes. Two you can read as diffs:
- Dev server exposing private data (commit
af467be): Codex wrote a startup test requesting a dummy file underdata/directly and via/@fs; it returned HTTP 200. The fix addeddata/,.envand key files to Vite'sfs.deny; the same test now asserts 403. - Incoming raid ignored after a completed relay (commit
687e383, found in our final live session): a partner inhomeignored a crew raid because the transition only acceptedidle. Codex added the failing test "receiving partner in home accepts a new raid from a crew member" (plus one proving outside raids are still ignored), then changed one condition.
- Dev server exposing private data (commit
- The work log grew with the tests:
docs/codex-log.mdhas 50 dated entries (prompt summary, files touched, tests added, bugs found); the suite grew from 14 tests to 181. - Division of labour: Codex wrote and tested the code, ran the evaluations and benchmarks, and documented results. We (humans) set the brief and rules, did Twitch OAuth and OBS setup, ran the live streams, reviewed every result, and produced the video.
How we built it
Stack: TypeScript (strict), Node 22, Fastify, node:sqlite, Vite, obs-websocket v5, Twitch EventSub WebSocket and Helix with plain fetch, OpenAI Responses API with strict structured outputs (openai/gpt-4.1-mini via OpenRouter; AI_BASE_URL switches to OpenAI directly), Web Audio + pitchy, ZXing (geometry only), ffmpeg.
Architecture in one line: frame → generic clues (model) → pure score with temporal accumulation (tested code) → action (OBS / Twitch).
What's real and what's simulated
| Flow | Status |
|---|---|
| Real vision on a live OBS stream crossing 80 → privacy scene in the viewer's Twitch player + stream marker; Dismiss restores the exact previous scene | ✅ Real, on Twitch |
| Private blocked term held by AutoMod; location-guessing message flagged with ID-only audit | ✅ Real, on Twitch |
| Full two-channel raid round trip (suggestion → raid → covering overlay → tag back → home), EventSub-confirmed | ✅ Real, on Twitch |
| Pre-stream check on our real OBS setup; OBS disconnect mid-stream → "analysis unavailable", no action | ✅ Real |
| QR Guard on the recorded OBS program output: 0/539 QR frames protected vs 93/538 unprotected | ✅ Real, offline recording of the encoded program |
| QR Guard through the Twitch player | ⚠️ Unverified: viewer-side trials were inconclusive |
| IRL footage and "tired" voice | ⚠️ Licensed stock clips and processed TTS audio, labeled SIMULATED; the analysis on them is real |
Measured, with limits
- Latency from frame capture to confirmed privacy scene (vision call + tested decision + OBS): median 2.15 s, p95 2.62 s (n=10, controlled benchmark). Sampling interval and Twitch's own stream delay come on top, which is why the score is built on clues accumulating over time, not censoring a single frame.
- Evaluation (
npm run eval, labels frozen before inference, hashes indocs/EVAL.md): on 12 author-labelled temporal sequences at the action threshold, recall 66.7% (about a third of exposures are missed) with precision 100%. Single frames rarely trigger by design. Chat classifier: 100%/100% on 40 synthetic messages, a small and easy set. - QR Guard: detection → privacy scene ~6–10 ms; 32/36 synthetic QR frames detected, 0 false positives on 24 IRL frames; small codes (36–48 px) are the weak spot.
- Model choice: we also tested GPT-6.1 Terra on the same frozen data and kept GPT-4.1 mini for live paths (faster, fewer unavailable analyses).
- Small datasets; not proof of real-world safety. Spotter is a safety net, not a guarantee.
Ethics and privacy by design
- No location is ever produced, stored or shown; clues are generic categories, never the text seen.
- Frames are sent to the configured model provider (OpenRouter by default) for analysis and are never written to disk by Spotter. They are frames the streamer is already broadcasting.
- Audio never leaves the browser; only numbers do. The public overlay never shows the score or the clues.
- Every action is reversible or needs a click: privacy can be dismissed, raids need approval, chat deletion is opt-in.
Prior art
Pixel-level tools blur individual details (a face, a plate, a QR code). Spotter also covers QR codes, but its core reasons about combinations of identifying clues over time, acts on Twitch and OBS, never outputs a location, and connects exposure to the streamer's energy and crew.
Challenges we ran into
- Measuring tiredness honestly: vocal fatigue only holds up against a person's own baseline, so Spotter reports energy relative to you and never claims to detect fatigue.
- Twitch in the real world: stream markers need stored broadcasts; raids need both channels live, the broadcaster's own token, and raider accounts old enough for the target's settings.
- OBS edge cases: blank browser sources, a transition-lock bug that kept the program stuck in Privacy, and races between Dismiss and an in-flight analysis — each turned into a regression test.
Accomplishments that we're proud of
- The privacy scene reaching a real viewer's Twitch player, and a full two-channel raid round trip on real Twitch.
- A published evaluation with its weaknesses visible.
- A design that refuses to output the very thing it protects.
What we learned
A vision model is a good witness and a bad judge. Keeping it to generic observations, and putting every decision in small tested functions, made the system safer and easier to trust.
What's next
- A larger, independently labelled natural evaluation set and repeatable viewer-side QR proof.
- Natural-microphone validation for Second Wind over long real streams.
- A hosted crew service so Tag Out works without local setup.
Try it
npm ci && npm run demo # scripted demo, no keys needed (SIMULATED) → http://127.0.0.1:5173/dashboard/
npm test # 181 pass
Real mode needs a Twitch app, OBS WebSocket and a model key; see README.
Footage credits: Pexels clips by 거열 박, George Morina, Ambient_Nature_ Atmosphere and Sururi Ballıdağ Director, plus Pexels videos 17363866 and 15329614 used as illustration (Pexels licence). In the video, real QR codes, licence plates and prominent brand logos in that footage are pixelated by us. Music and sound effects are original, synthesized for this video. Twitch UI screenshots show our own test channels (Spanish-language UI).
Built With
- codex
- fastify
- node.js
- obs-websocket
- openai
- pitchy
- sqlite
- twitch-eventsub
- twitch-helix
- typescript
- vite
- web-audio-api
- zxing