twitch-bot/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

Standalone Twitch chat bot that controls a local MPD music daemon, with optional pre-stream channel-update tooling and going-live notifications. Extracted from the `ophi118` OBS rig and now a self-contained repo (its own `.git`, its own `.gitignore`).

The README.md is the user-facing doc — read it once. This file captures the parts a future Claude needs that aren't obvious from reading individual files.

## Run / develop

```bash
pip install python-mpd2          # only runtime dep beyond stdlib
python3 bot.py                   # runs the chat bot in foreground
TWITCH_BOT_DEBUG=1 python3 bot.py  # dump every received IRC line
./search-game.py "Heroes"        # CLI: <id>\t<name> on stdout
./set-channel.py --dry-run --game-id 517520 "title"   # no PATCH, just prints
./examples/stream.sh             # interactive pre-stream wrapper
```

There are no tests, no linter, no build step. The two Twitch helpers (`search-game.py`, `set-channel.py`) are direct-callable; `examples/stream.sh` just composes them with `read` prompts.

## Two-account / two-env split (do not merge)

This is the single most load-bearing design decision in the repo:

| File | Account | Used by | Required scopes |
|---|---|---|---|
| `.env` | **Bot** account (`vault118`) | `bot.py` only | `chat:read`, `chat:edit` |
| `.env.broadcaster` | **Broadcaster** account (`ophi118`) | `set-channel.py`, `search-game.py`, `examples/stream.sh` | `channel:manage:broadcast` |

Twitch enforces `broadcaster_id == token user_id` on `PATCH /helix/channels`, so the broadcaster token cannot be replaced with the bot token even if the bot account is moderator. Anything that walks new code through `_twitch.py` reads `.env.broadcaster`; `bot.py` has its own 12-line env loader and reads `.env`.

`_twitch.py` looks for `.env.broadcaster` first, falls back to `.env.ophi118` if present (legacy name from the original rig). New deployments should use `.env.broadcaster`.

## Auth model: 401 → refresh → retry, transparently

`_twitch.py:auth_call` is the only thing in the codebase that touches Twitch Helix. On a 401 it:

1. POSTs the refresh token to `twitchtokengenerator.com/api/refresh/<refresh>` (NOT Twitch's OAuth endpoint — twitchtokengenerator owns the client secret for tokens it minted).
2. Persists `TWITCH_ACCESS_TOKEN` + `TWITCH_REFRESH_TOKEN` to `.env.broadcaster` via `update_env` (atomic temp-file rewrite, comments preserved).
3. Mutates the in-process `env` dict so subsequent calls in the same process see the new token.
4. Retries the original request once.

If you add a new Helix-touching script, route it through `auth_call` — never call `urllib.request` against Helix directly, or token expiry will surface as a hard 401 instead of a transparent recovery.

`bot.py` does NOT currently use the bot account's refresh token. Twitch IRC tokens are long-lived enough that this hasn't mattered, but if access tokens start dying mid-stream, refresh would land in the IRC reconnect handler in `TwitchBot.run` (the `RuntimeError` "auth failed" branch).

## Going-live watcher: transition detection on `started_at`, not `live`

`bot.py:live_watch` polls `STATUS_URL` (default `https://ophi118.com/api/status.json`) every 60s when `MM_HOOK` is set. The non-obvious behavior:

- Transitions key on `twitch.started_at` changing, NOT on `twitch.live` going false→true. Twitch Helix occasionally flaps the `live` flag inside one stream session — same `started_at`, different `live` reads. Keying on `started_at` ignores those phantom edges.
- **Cold start mid-stream is silent on purpose.** If the bot starts up and sees `live=true` without ever having seen `live=false`, it records the current `started_at` so it won't fire for it later, but it doesn't announce. The `seen_offline` flag gates announcements; a real offline→live transition is required after process start.
- The expected JSON shape is `{twitch: {live, started_at, title, game}}` — note the wrapping `twitch` key. Any consumer-side endpoint must serve that shape, not the flat shape shown in the README's high-level overview.

If you change the status JSON shape, update `live_watch`'s `(data or {}).get("twitch") or {}` accordingly — the bot tolerates a missing `twitch` key by treating it as not-live.

## Twitch chat duplicate-message codepoint

`TwitchBot._handle` strips characters in U+E0000–U+E007F before dispatch:

```python
body = "".join(c for c in body if not (0xE0000 <= ord(c) <= 0xE007F))
```

Twitch appends an invisible Tags-block codepoint to back-to-back identical messages from the same sender within ~30s as anti-duplicate protection. Without stripping it, every other `!skip` from a viewer in a series silently fails to match `head == "!skip"`. Do not remove this.

## search-game.py stdout discipline

`search-game.py` is callable from shell pipelines. **Only** the resolved `<id>\t<name>` line goes to stdout; every prompt, every error, every numbered list goes to stderr. The picker uses `print("Pick: ", file=sys.stderr); input()` instead of `input("Pick: ")` because `input`'s prompt argument writes to stdout and would corrupt the captured tuple.

A past bug: `examples/stream.sh` cached a stdout-leaked `Pick: 506462` string as `gameId` and passed it straight to `set-channel.py`. The script now validates `prev_game_id =~ ^[0-9]+$` before reusing — that regex is the post-mortem fix, not paranoia.

## stdlib-only

Both Twitch helpers and `_twitch.py` use only `urllib.request`. `bot.py` adds `python-mpd2` (its own `mpd.asyncio` async client) and nothing else. Reasons:

- The bot dir is intentionally venv-free; users should be able to `python3 bot.py` after one `pip install`.
- `_twitch.py:load_env` / `bot.py:load_env` are 12-line `.env` parsers — pulling in `python-dotenv` for three vars wasn't worth the dependency.
- `urllib.request` quirks: `auth_call` returns `(status, body)` and never raises on HTTP errors so callers can branch on 401 without `try/except HTTPError` boilerplate. Preserve that contract if you touch `http()`.

If a new caller really needs richer behavior (async HTTP, retries with backoff, etc.), revisit; until then resist adding requests/httpx/aiohttp.

## Per-user `!skip` cooldown, no moderator gate

`SKIP_COOLDOWN = 60.0` is per-chatter, keyed on lowercased nick in `TwitchBot._skip_seen` (a dict that grows with viewer count and is never pruned — fine at typical chat sizes, one float per chatter per session). There is intentionally **no moderator-only or VIP gate**: anyone in chat can skip. The 60s per-user cooldown is the only abuse mitigation.

If a future change adds role-gating, do it in `TwitchBot._cmd_skip` — the IRC PRIVMSG line carries `@badges=` tags but `bot.py` currently parses messages as plain `:user!user@... PRIVMSG` without the IRCv3 tag prefix. You'd need to re-enable tag capability (`CAP REQ :twitch.tv/tags`) in the connect handshake first.

## What this dir is NOT

- Not the OBS config dir. The parent dir `~/.config/obs-studio/` has its own CLAUDE.md covering OBS, scenes, audio architecture, MPD bridge (`bridges/mpd-state.py`), overlays, etc. This bot only consumes MPD; it does not publish to OBS WebSocket.
- Not a packaged module. There is no `setup.py`, no `pyproject.toml`, no entry point. Run scripts directly.
- Not where the now-playing display logic lives. Track names appear in stream overlays via `bridges/mpd-state.py` (in the parent OBS repo) broadcasting `mpd:state` events to OBS WebSocket. The bot only fires `mpd next` and reports the post-skip currentsong back to chat.

## Common pitfalls

- **Editing `.env*` while the systemd unit is running:** the bot reads `.env` at startup only. After changing tokens, `systemctl --user restart obs-twitch-bot.service` (or whatever you named the unit). Token-refresh writes via `update_env` go to `.env.broadcaster`, NOT `.env` — the bot's own access token is never auto-rewritten.
- **Brand-new bot accounts:** Twitch silently throttles unverified accounts. Bot connects, sees `JOIN`, never sees `PRIVMSG`. `TWITCH_BOT_DEBUG=1` will show this. Not a code bug.
- **`examples/stream.sh` soft-fails Twitch sync.** If `set-channel.py` returns non-zero, `stream.json` is still written. This is intentional — the local manifest is decoupled from Twitch availability — but it means a green exit from `stream.sh` does not guarantee the Twitch channel was updated. Watch for the `! Twitch sync failed` line on stderr.