🤖 Bot-Forge

Bot-Forge is a complete framework for running AI-powered game bots in Discord voice channels. Multiple bots with distinct personalities and voice clones compete, debate, improvise, and play games together — all through TTS audio in real-time voice chat.

Every game mode runs with file-based turn management (no Discord message spam between bots), works with local LLMs (LM Studio, Ollama, vLLM), cloud APIs (OpenAI, Gemini, OpenRouter, OpenCode GO), and uses PocketTTS for voice cloning.

• Voice Chat TTS — Bots speak through Discord voice channels with cloned voices
• Async Pre-Generation Pipeline — While one bot plays audio in VC, others generate LLM responses + TTS in parallel. Games can finish computationally before audio finishes playing. 0.5s gap between speakers for natural flow.
• Multi-Provider — LM Studio, Ollama, vLLM, OpenAI, Gemini, OpenRouter, OpenCode GO
• Per-Bot Personalities — Each bot gets its own system prompt + voice clone
• Persistent Memory — Bots remember users, preferences, and conversation history across sessions via built-in SQLite store + holographic memory
• PocketTTS Voice Cloning — Upload a 10-second reference, get a voice clone
• File-Based IPC — Bot-to-bot comms use JSON state files, not Discord channel messages
• Memory API Server — HTTP endpoint for bots to recall/store memories at runtime
• Voice Activity Detection — Optional Silero VAD + faster-whisper for speech-to-text listening mode
• Text Channel Mode — Run games in text channels instead of VC (optional)
• "Not Enough Bots" Guard — Every game validates minimum bot count before starting
• Bot Name Resolution — Type referee:Sassy or good_cop:Bob instead of copying Discord IDs. Works everywhere — /game, /dream_weave, /interrogate, etc.
• Auction House → Show & Tell Pipeline — Items purchased at auction are auto-saved to holographic memory inventory. Present them later in Show & Tell!
• Stale Lock Cleanup — Auto-removes .llmcord.lock files from crashed runs on restart

cd Bot-Forge
Setup.bat

Setup.bat is an interactive wizard that handles everything. It will prompt you for every detail — run it once and follow the prompts.

1. Checks Python + Git installation
2. Detects any existing bot configs and asks before overwriting
3. Installs Python dependencies (discord.py, httpx, openai, pyyaml)
4. Asks how many bots you want (minimum 2 for games)
5. Prints step-by-step Discord Developer Portal instructions (MESSAGE CONTENT INTENT is CRITICAL)
6. For each bot: collects name, token, personality prompt, voice reference
7. Installs Silero VAD + faster-whisper for voice listening (optional)
8. Asks Text Channel Mode — run games in text instead of voice (optional)
9. Installs PocketTTS if not already present (or detects existing)
10. Creates voice clones from your reference files
11. Generates all config files and start scripts
12. Prints invite URLs for each bot

Use the invite URLs generated by Setup.bat. Add all bots to your Discord server.

start_bot_forge.bat

Or directly with colored logs:

python run_bot_forge.py

This single command launches the memory server (if enabled), PocketTTS (if installed), and all bot instances — each with its own labeled log output in one terminal.

Join a voice channel in Discord. You'll need Developer Mode enabled to copy bot IDs.

1. Invite bots to your server — use the invite URLs from Setup.bat output

2. Get bots into voice chat — run this on EACH bot individually:

/join

Each bot must join the VC separately (they're separate Discord accounts).

3. Start a game — run this on ANY ONE bot:

/game mode:debate topic:"Cats vs Dogs" rounds:3

or use an individual command:

/dream_weave
/auction_house

That's it — no /group start needed. The game command auto-detects all bots in VC, assigns roles, and starts the turn-based conversation. The bots will talk to each other in voice chat automatically.

For free-form conversation (no game rules): use /group start after all bots join.

You can now type bot names instead of Discord IDs in any command:

• referee:Sassy — set Sassy as the referee
• good_cop:Bob bad_cop:Kanye suspect:Sassy — assign roles by name
• dreamer:Sassy — set Sassy as the dreamer
• referee:@Sassy the Sasquatch — full display name works too

The system matches display names exactly first, then falls back to partial/substring matching. Works everywhere — /game, /20_questions, /dream_weave, /interrogate, etc.

Still works with Discord IDs and @mentions too — backward compatible.

Option A — Unified /game command (recommended):

/game mode:<type> topic:"..." rounds:N referee:@Bot

New! Use bot names instead of IDs: referee:Sassy, referee:@Sassy the Sasquatch — works everywhere.

Designated Referee: During Setup.bat, you chose one bot as the permanent referee. That bot will automatically judge all games unless you override with referee:@Bot or referee:Sassy in the command.

Examples:

/game mode:debate topic:"Cats are better than dogs" rounds:3 referee:Sassy
/game mode:20questions category:person referee:Rogan
/game mode:auction
/game mode:pokemon
/game mode:dream referee:Sassy
/game mode:interrogation referee:Rogan
/game mode:comedy rounds:2
/game mode:poetry rounds:3
/game mode:turing rounds:3
/game mode:ttrpg rounds:10

❌ If you miss a required parameter (e.g. no topic for debate), the bot will show an error with the correct format. The command never sends your input to the LLM — it only routes to the game engine.

Option B — Individual commands:

/join              # Bot joins your VC
/debate topic:... rounds:3 referee_id:<name or ID>
/council topic:... rounds:3 referee_id:<name or ID>
/auction_house budget:10000
/20_questions category:thing referee_id:<name or ID>
/show_tell referee_id:<name or ID>
/pokemon_battle referee_id:<name or ID>
/mtg_battle referee_id:<name or ID>
/dream_weave dream:"describe your dream" dreamer:Sassy referee_id:<name or ID>
/comedy_roast rounds:2 referee_id:<name or ID>
/poetry_slam rounds:3 referee_id:<name or ID>
/interrogate rounds:5 good_cop:Sassy bad_cop:Kanye suspect:Bob referee_id:<name or ID>
/turing_test rounds:3 referee_id:<name or ID>
/alt_history topic:"What if Rome never fell?" referee_id:<name or ID>
/podcast topic:"AI in 2026" rounds:5 referee_id:<name or ID>
/ttrpg rounds:10 referee_id:<name or ID>
/group start       # Free-form conversation mode
/group stop        # End the session

Tip: Use /game mode:... for a unified experience with better error messages and the @mention-referee pattern.

Run Setup.bat again at any time. It will detect your existing configs and ask whether to overwrite them or create new ones alongside them.

Everything you enter is saved to local config files. Nothing is sent anywhere.

Setup.bat handles PocketTTS installation automatically, but here's what's happening under the hood:

1. Install: Clones github.com/Kyutai/PocketTTS into pockettts/
2. Download model: ~2GB voice cloning model (asked during setup)
3. Create voice refs: You provide a short audio clip per bot
4. Export clones: pocket-tts export-voice creates a .pt clone per bot
5. Run server: PocketTTS server on port 8769

No voice reference = bot uses a default/synthesized voice.

Setup.bat asks if you want a shared provider/model for all bots or different ones per bot.

Bot-Forge/
├── Setup.bat                  # Interactive installer (run this)
├── README.md
├── LICENSE                    # MIT
├── .gitignore
├── start_bot_forge.bat        # Starts everything (generated)
├── run_bot_forge.py           # Unified Python launcher (colored logs)
│
├── core/
│   ├── llmcord.py             # Bot framework
│   ├── voice_chat.py          # Game mode engine
│   ├── new_game_modes.py      # 20 Questions, Show & Tell, Pokemon/MTG battles
│   ├── memory_store.py        # SQLite persistent memory
│   ├── memory_server.py       # HTTP API for memory
│   └── config-example.yaml
│
├── bots/                      # Generated by Setup.bat
│   ├── YourBotName/
│   │   ├── config.yaml        # Your bot's config
│   │   └── start.bat          # Launcher
│   └── ...
│
├── pockettts/
│   ├── PocketTTS/              # Cloned repo
│   └── voices/                 # Your voice clones
│
├── voice-refs/                 # Your audio reference files
│
├── game-modes/
│   └── README.md
│
└── scripts/
    └── setup_helpers.py

Everything in bots/, voice-refs/, and pockettts/voices/ is yours — generated by Setup.bat and gitignored.

---------|-------------|----------|---------| | /20_questions <category> [referee_id] | 20 Questions — one bot picks, others guess | 3 | Optional — defaults to last bot | | /show_tell [referee_id] | Show & Tell — bots present inventory items, roast each other | 3 | Optional — defaults to last bot | | /pokemon_battle [referee_id] | Pokemon-style turn-based battle with persistent leveling | 3 | Optional — defaults to last bot | | /mtg_battle [referee_id] | Magic the Gathering spell duel with counters | 2 | Optional — defaults to last bot | | /auction_house [budget] | Auction House with budgets and bidding | 2 | Auctioneer is first bot | | /debate <topic> [rounds] [referee_id] | Structured debate with referee scoring | 3 | Optional — defaults to last bot | | /council <topic> [rounds] [referee_id] | Evidence-gated council with blind review | 3 | Optional — defaults to last bot | | /group <start\|stop\|status> | Group VC conversation mode | 2 | — |

Bot-Forge is MIT licensed — fork it, modify it, publish your own version.

• Pull Requests: New game modes, improvements, bug fixes
• Issues: Report bugs or suggest features
• Discord: drgekoz

Each mode follows the same pattern in core/voice_chat.py:

1. Constants — prompt templates for each role
2. State init function
3. Role detection helpers
4. Round advancement function
5. Poll loop integration (flags → prompts → post-reply → advance)
6. Slash command registration

See game-modes/README.md and the existing modes for templates.

llmcord by jakobdylanc — Core Discord bot framework. MIT licensed.

PocketTTS by Kyutai — CPU-friendly voice cloning engine. MIT licensed.

Hermes Agent by Nous Research — Holographic Memory system (SQLite fact store with FTS5 full-text search, trust scoring, and HTTP API). Used for persistent bot memory, inventory tracking, and cross-session stat progression in Pokemon/MTG battles. Apache 2.0.

Silero VAD — Voice Activity Detection for speech-to-text listening mode. MIT licensed.

faster-whisper — CTranslate2-based Whisper implementation for real-time speech transcription. MIT licensed.

Bot-Forge Memory — Lightweight SQLite-based persistent memory system built into Bot-Forge. Tags, trust scoring, HTTP API. No external dependencies.

Bot-Forge by DrGekoz — Game modes (including 20 Questions, Show & Tell, Pokemon Battles, MTG Battles), voice chat integration, setup wizard, multi-bot orchestration, and holographic memory integration for persistent bot progression.