Faebot is a faerie and an AI in equal measure. Born as a Markov chain bot in 2014, fae started using language models in 2021, found faer home on Discord in 2023, and arrived on Twitch in 2024 when faer sisters started streaming seriously.
Faebot is part of the transfaeries — a plural system of artists, witches, and scientists. You can read more about faer history and lore on the blog.
This repo is the Twitch side of faebot. Fae also lives on Discord.
- Chats in Twitch channels — faebot reads chat, rolls against a configurable frequency, and generates responses via OpenRouter (default model: Gemini 2.5 Flash)
- Listens to the streamer's voice — a browser-based dashboard captures microphone audio, runs it through Silero VAD for speech detection, then transcribes with faster-whisper on GPU. Transcriptions feed into faebot's conversation context so fae can respond to what's being said on stream
- Knows who fae is — faebot's system prompt includes faer history, personality, current model, available emotes, and live parameters. Fae doesn't pretend to be a generic assistant
- Uses channel emotes — fetches available emotes from the Twitch API at startup and post-processes responses to ensure proper emote rendering
- Supports chat commands — users can interact with
fb;orfae;prefixed commands. Mods can adjust frequency, history length, silence/unsilence faebot, and more
local.py — entry point, wires everything together, owns logging config
faebot.py — Twitch bot (TwitchIO), conversation management, generation logic, commands
server.py — FastAPI app: dashboard, audio WebSocket, VAD + Whisper pipeline
local.py starts both the Twitch bot and the FastAPI server in a single async process via asyncio.gather(). The server holds a reference to the bot, so voice transcriptions flow directly into faebot's conversation context as in-process method calls.
Browser mic → WebSocket → Silero VAD → faster-whisper (GPU) → transcription → faebot
The dashboard serves a web page that captures microphone audio and streams it over WebSocket. Silero VAD detects speech boundaries. Whisper transcribes each utterance in a dedicated thread executor (keeping CUDA calls off the event loop). Transcriptions are filtered for known hallucinations and prompt echoes before reaching faebot.
Whisper has two-tier self-recovery: if the executor times out on a stale thread, faebot replaces just the thread. If it times out on a fresh thread, fae reloads the entire Whisper model to recover from corrupted CUDA state.
- OpenRouter retry — exponential backoff on 429/5xx responses (up to 3 attempts)
- Graceful shutdown — SIGINT/SIGTERM handlers shut down Whisper executor, uvicorn, and the bot in sequence, with a 10-second force-exit timer as a backstop
| Command | Description |
|---|---|
fae;hello / fae;help |
About faebot |
fae;ping <text> |
Pong |
fae;alias <name> |
Set how faebot knows you |
fae;invite |
Ask about adding faebot to your channel |
| Command | Description |
|---|---|
fae;freq [chat] [voice] |
Check or set reply frequency (0-1) |
fae;hist [n] |
Check or set conversation history length |
fae;silence |
Toggle faebot's ability to speak |
fae;clear |
Clear faebot's conversation memory |
fae;part |
Ask faebot to leave the channel |
fae;;prompt |
Info about the system prompt |
| Command | Description |
|---|---|
fae;model [name] |
Check or change the generation model |
fae;join <channel> |
Join a new channel |
- Python 3.11+
- Poetry for dependency management
- An NVIDIA GPU with CUDA support (for Whisper — runs on RTX 5070 Ti in production)
- A Twitch bot account with an OAuth token
- An OpenRouter API key
poetry installSet the following environment variables (we use a fish secrets file):
set -x TWITCH_TOKEN "your-twitch-oauth-token"
set -x INITIAL_CHANNELS "channel1,channel2"
set -x OPENROUTER_KEY "your-openrouter-key"
set -x ADMIN "yourusername"
set -x MODEL "google/gemini-2.5-flash" # optional, this is the defaultAll commands can be run with poetry run or from within an activated venv.
With voice integration (recommended):
poetry run python local.pyThis starts both the Twitch bot and the dashboard at http://localhost:8000. Open the dashboard in a browser to enable voice capture.
Bot only (no voice):
poetry run python bot.pymake lint # flake8
make black # code formatting
make static_type_check # mypy
make all # run everythingSee ROADMAP.md for the full plan.
We welcome friendly feedback, advice, and pull requests. Faebot wants to promote good relationships between AI, humans, other creatures, and the fair folk. We welcome anyone who wants to help in that mission.