TwitchPulse

TwitchPulse maps Twitch Channel Points custom reward redemptions to keyboard and mouse actions in a selected Windows app or game.

This is a rebuild of the old monolithic bot. The new implementation lives in src/twitchpulse. Legacy files can be kept locally for reference, but they are intentionally excluded from the repository.

Why this architecture

• Twitch integration uses EventSub WebSocket for channel.channel_points_custom_reward_redemption.add.
• Token checks follow Twitch's current requirement to validate OAuth tokens on startup and hourly in long-running apps.
• Input uses WinAPI SendInput scan-code events instead of the old global keyboard hook path.
• Targeting is fail-closed by default. If the configured game window is not found, TwitchPulse skips the action instead of sending keys to the active Windows app.

Setup

1. Create or update a Twitch app in the Twitch Developer Console.
2. Use a user token with channel:read:redemptions or channel:manage:redemptions.
3. Install and create config:

python -m venv .venv
.\.venv\Scripts\activate
python -m pip install -r requirements.txt
python -m pip install -e .
python -m twitchpulse init --config config.json

4. Edit config.json:

• twitch.channel_login: your Twitch channel login.
• twitch.client_id: Twitch app client ID.
• twitch.access_token: optional user access token. Prefer auth-device, which stores token data in twitch.token_path.
• profiles[].processes: process names such as RobloxPlayerBeta.exe.
• profiles[].rewards: reward title to action mapping.

Commands

python -m twitchpulse validate --config config.json
python -m twitchpulse doctor --config config.json --list-windows
python -m twitchpulse simulate-redemption --config config.json --reward "Jump" --allow-active-window-fallback
python -m twitchpulse auth-device --config config.json
python -m twitchpulse run --config config.json

Action syntax

• space: press a key once.
• hold:w:0.75: hold a key for seconds.
• mouse:left: click a mouse button.
• wait:0.2: wait inside a sequence.
• JSON sequence:

{
  "type": "sequence",
  "steps": ["hold:w:0.3", "mouse:left", "wait:0.1", "space"]
}

Multimedia keys such as volume_mute are rejected by default.

Known limits

• Real Twitch validation requires a live Twitch account and token.
• Some games, anti-cheat systems, or elevated windows can ignore synthetic input.
• Roblox may accept scan-code SendInput, but this must be verified on the actual target experience.
• The current shell does not have git, so no branch or commit was created during this rebuild.