Hint Vault

Inspiration

Puzzle streamers love their chat, but unsolicited solutions ("just pull the red lever") spoil the moment the streamer wanted to earn. We wanted chat to keep helping without taking the puzzle away.

What it does

• Viewers post !hint <tip> in Twitch chat. Each tip is sealed and stays hidden on the overlay.
• When the streamer types !stuck, the vault opens. Similar tips are grouped, rated from gentle nudge to full solution, and revealed gentlest first. !more reveals the next level.
• Hints that look like direct solutions are held back by a spoiler filter.
• When a room is solved, a "Helped" board credits the viewers whose tips were used.
• Privacy is built in: hints live in memory only, and !forgetme deletes a viewer's data. Data is also purged when the stream goes offline.
• Ships with Lumen Locks, an original three-room browser puzzle game, an OBS browser-source overlay, an admin page, and an offline demo mode with clearly labelled simulated viewers.

How we built it

• Node.js with no dependencies: built-in HTTP server, a hand-written RFC 6455 WebSocket server, and node --test.
• Twitch EventSub WebSocket (channel.chat.message, stream.online/offline) and Helix chat/messages, authorized with the OAuth Device Code Flow.
• Safety guards: sending is a dry run by default, replies are rate-limited and capped, and the token is never logged.
• Tested live on 31 Oct 2026 on twitch.tv/3rnest: 8 approved messages were received over EventSub and processed end to end.

How Codex was used

The entire app was built in a single Codex CLI thread (session 01a182eb-9111-7860-9f26-1f06ddc01557) across five build prompts: offline scaffold and mock pipeline; game and stage; lifecycle, spoiler and privacy hardening; Twitch EventSub/Helix integration with local fakes; review. Codex wrote the server, game, overlay, pipeline modules, Twitch adapter and test suite (44 tests). A human reviewed every step, ran the live tests and committed each step.

Challenges we ran into

• Testing real Twitch chat safely without spamming a real channel.
• Handling the broadcaster's own messages without the bot replying to itself.
• Rate limits for hints and replies.
• Implementing WebSockets without libraries.

Accomplishments that we're proud of

A working end-to-end loop on real Twitch chat, an original game built for the demo, a privacy-first design with no chat text on disk, zero dependencies and a fully offline demo mode.

What we learned

How EventSub WebSocket sessions behave, that good defaults (dry run, caps) make live testing calm, and that small, reviewed Codex steps keep one long thread coherent.

What's next for Hint Vault

Swap the mock rater for an AI provider behind the existing adapter seam with a cost cap, add channel-point integration, and support more games through a simple puzzle-event API.

Built With

• ffmpeg
• html/css/svg
• javascript
• node.js
• oauth-device-code-flow
• openai-codex-cli
• piper
• twitch-eventsub
• twitch-helix-api
• web-audio