Rounds
One app for a whole game night. v1 ships one game, Password: two teams of two, played on the host's phone.
The clue-giver gets the secret word on WhatsApp from an Agent 37 agent. Rules and scoring live only in the app.
See docs/PLAN.md for the product plan and the decisions behind it.
Run it
npm install
npm run dev # http://localhost:3000
npm test # game engine tests
npm run typecheck
The game works without any setup. With no WhatsApp relay configured, each word shows on the host phone
behind a tap-to-reveal screen, and the timer is held until the clue-giver hides it.
Environment
| Variable | Where | What |
|---|
AGENT37_WEBHOOK_URL | server | The Hermes webhook route on the Agent 37 instance, e.g. https://webhooks-<id>.agent37.app/webhooks/rounds. Leave unset to play without WhatsApp |
AGENT37_WEBHOOK_SECRET | server | The route's HMAC secret, used to sign each request |
NEXT_PUBLIC_GAME_WA_NUMBER | build | The agent's WhatsApp number with country code, e.g. 919800000000. Used for the fallback "send hi" link if a welcome message doesn't get through |
What the agent receives
POST /api/notify renders one of five fixed templates on the server (welcome, word, skip, score, winner), so the relay
can't be used to send arbitrary text. It then makes one request per recipient:
POST $AGENT37_WEBHOOK_URL
X-Webhook-Timestamp: <unix seconds>
X-Webhook-Signature-V2: <hex HMAC-SHA256 of "<timestamp>.<body>" with $AGENT37_WEBHOOK_SECRET>
X-Request-ID: <matchId>:<turn>:<kind>:<phone>
Content-Type: application/json
{"to": "919812345670", "text": "🔒 Turn 5 · Your word: *MANGO*\nOne-word clues only. Don't show anyone.", "idempotency_key": "..."}
On the agent this is a Hermes webhook route with deliver_only: true: Hermes checks the signature, drops a
repeated X-Request-ID, and sends text to to on WhatsApp exactly as given, with no LLM in the path. After setup the app sends each player a welcome message, so nobody has to message the game first.
Layout
app/ routes: / (home), /password (setup → message everyone → play), /night (tonight's board)
app/api/notify/ Agent 37 relay
components/password/ Setup, Optin, Play, EditMatch screens and the useGame hook
lib/engine/ pure game rules (reducer) + tests
lib/words/ word packs
lib/notify/ message templates and the client
lib/store/ localStorage: current match, remembered players, night tally, local analytics
