gigabuttsbot

A Twitch IRC bot that occasionally re-posts a user's chat message with one or more words/syllables replaced by "butt".

Setup

1. Register an application at https://dev.twitch.tv/console/apps to get a Client ID and Secret.
2. Create a separate Twitch account for the bot. (You won't need to share its password with this app — you'll log in to it in your browser.)
3. Copy .env.example to .env and fill in TWITCH_CLIENT_ID, TWITCH_CLIENT_SECRET, and TWITCH_CHANNEL (the channel the bot should join).

Install dependencies:

uv sync --extra dev

First run / logging in

The bot stores its OAuth tokens in gigabuttsbot.db (SQLite, gitignored) and refreshes them automatically. You only log in once per bot account.

uv run gigabuttsbot

If no tokens are stored yet, the bot prints something like:

To authorize the bot:
  1. Open a private/incognito browser window (so it doesn't use your main Twitch account)
  2. Log in to your bot's Twitch account
  3. Visit:  https://www.twitch.tv/activate
  4. Enter code:  ABCD-1234

Waiting for authorization... (Ctrl+C to cancel)

Follow the on-screen steps. Using a private/incognito window is important — otherwise your browser will use whichever Twitch account you're currently signed in to (likely your main account, not the bot account).

Once you authorize in the browser, the bot stores the access + refresh tokens locally and starts up. Subsequent runs skip the login step entirely.

Switching bot accounts

uv run gigabuttsbot logout    # clears stored credentials
uv run gigabuttsbot login     # re-runs the device-code flow

gigabuttsbot login also works any time to re-authorize without first logging out (it overwrites whatever was stored).

Test

uv run pytest

Chat commands

Admin commands (broadcaster + moderators only):

• !buttsbot on / !buttsbot off — enable or disable buttification entirely.
• !buttsbot freq <0.0-1.0> — probability that any given eligible message gets buttified. 0.0 = never, 1.0 = every message, 0.05 = ~5% of messages.
• !buttsbot cooldown <seconds> — minimum seconds between buttified messages. The bot stays silent until this much time has passed since its last reply. 0 disables the cooldown.
• !buttsbot word <word> — the replacement word. Defaults to butt. Example: !buttsbot word toe.
• !buttsbot ratio <0.0-1.0> — when a word is chosen for buttification, this is the chance it gets a syllable replaced rather than the whole word being swapped out. 0.0 = always replace the whole word, 1.0 = always replace just one syllable.
• !buttsbot extra <chance> <decay> — controls how often more than one word in a single message gets buttified. After the first replacement, there's a <chance> (0.0–1.0) of buttifying another word; if it happens, that chance is multiplied by <decay> (0.0–1.0) before rolling for the next one, and so on. Example: !buttsbot extra 0.5 0.5 → 50% chance of a 2nd, then 25% for a 3rd, then 12.5%, etc. <decay> 1.0 keeps the chance flat; 0.0 caps it at 2 words max.
• !buttsbot block <word> — add a word to the blacklist. Blacklisted words are never buttified. Matching is exact-word and case-insensitive (block butt protects butt/Butt/BUTT but not butts). Words must be letters/apostrophes only.
• !buttsbot unblock <word> — remove a word from the blacklist.
• !buttsbot blocked — list the blacklisted words. Long lists are truncated to the first 20 with a (+N more) suffix.
• !buttsbot status — print current settings.

Anyone:

• !buttout — opt out of buttification.
• !buttin — opt back in.