Stream CoHost Documentation

Welcome to the comprehensive documentation for Stream CoHost, the most advanced Twitch AI co-hosting system with 54+ production plugins, intelligent memory, and a full Virtual Host character platform.

What is Stream CoHost?

Stream CoHost is a live, production-grade Twitch AI co-hosting platform running on real streams right now. Unlike traditional chatbots, Stream CoHost features:

• Selective Memory System: AI analyzes conversations for emotional significance and automatically saves important community moments
• Virtual Host Platform: Multi-character animated AI co-hosts with stand-up routines, idle manager, and sequence builder
• Non-Blocking Plugin Hooks: The beforeOpenAI and afterOpenAI hook system ensures slow external calls never block chat responses
• Production-Ready Plugins: 54+ plugins including casino suite (8 games), trivia engine (9 modes), music system, and full admin control
• Professional Admin Control: Unified interface with dark/light themes, plugin management, and real-time configuration
• Performance Engineering: Centralized OpenAI service with response caching (50-70% cost reduction) and 0.11ms database queries

Installation Guide

Get Stream CoHost up and running in minutes with our comprehensive installation guide.

System Requirements

Quick Installation

# Download Stream CoHost
git clone https://github.com/streamcohost/streamcohost.git
cd streamcohost

# Install dependencies
npm install

# Copy configuration template
cp .env.example .env

# Start the bot
npm start

Configuration

Configure Stream CoHost with your Twitch credentials and AI service settings.

Environment Variables

Create a .env file in the project root with the following configuration:

# Twitch Configuration
TWITCH_USERNAME=your_bot_username
TWITCH_CHANNEL=your_channel_name
TWITCH_OAUTH_TOKEN=oauth:your_oauth_token

# OpenAI Configuration
OPENAI_API_KEY=sk-your-openai-api-key
OPENAI_MODEL=gpt-4
OPENAI_MAX_TOKENS=150
OPENAI_TEMPERATURE=0.7

# Bot Configuration
EXPRESS_PORT=3710
RESPONSE_MODE=chat
MAX_USER_MEMORY=50
MEMORY_CLEANUP_THRESHOLD=100
AUTO_RESET_ON_STARTUP=false

Getting Your Twitch OAuth Token

1. Visit Twitch TMI
2. Click "Connect" and authorize the application
3. Copy the OAuth token (starts with "oauth:")
4. Add it to your .env file

OpenAI API Setup

1. Create an account at OpenAI Platform
2. Navigate to API Keys section
3. Create a new API key
4. Add it to your .env file

AI Memory System

Learn how Stream CoHost's intelligent memory system works and how to configure it for optimal performance.

How It Works

The AI Memory System uses advanced natural language processing to:

• Analyze Emotional Significance: Detects important moments in chat conversations
• Selective Retention: Only saves memories that have lasting value
• Context Learning: Builds understanding of community dynamics and viewer preferences
• Smart Cleanup: Automatically manages memory storage to prevent bloat

Memory Categories

Configuration Options

// Memory configuration in botMemory plugin
const memoryConfig = {
    maxUserMemory: 50,        // Max memories per user
    cleanupThreshold: 100,    // When to trigger cleanup
    emotionalThreshold: 0.7,  // Minimum emotional significance
    retentionDays: 30,        // How long to keep memories
    categories: [
        'preferences',
        'achievements', 
        'community_events',
        'personal_info'
    ]
};

Music System

Comprehensive music management with visualizer, request system, and analytics.

Features

• Butterchurn Visualizer: Real-time audio visualizations
• Request System: Viewer song requests with queue management
• Music Analytics: Track popular songs and user preferences
• Overlay Integration: Stream overlay with now playing information

Setup Guide

1. Enable the Music plugin in the admin panel
2. Configure your music directory path
3. Set up the stream overlay
4. Configure request permissions and costs

Chat Commands

Virtual Host System

The VHost system lets you create and manage multiple animated AI virtual co-hosts, each with their own character, voice, video loops, and personality.

Features

• Animated Characters: WebM alpha-channel video loops for sitting, standing, and transition states
• TTS Voice Sync: OpenAI or ElevenLabs TTS synchronized with character animations
• Stand-up Routines: AI-generated stand-up comedy bits with configurable topic selection and 30-minute cooldown
• Sequence Builder: Visual drag-and-drop editor for chaining talk segments, pauses, and video clips
• Idle Manager: Automatic idle behavior and ambient animations between interactions
• YouTube Upload: Automatic recording and direct upload of VHost sessions to YouTube
• OBS Integration: Scene and source control synchronized with character state changes

Chat Commands

!standup [topic]    # Trigger a stand-up routine on the given topic
!idle               # Put the virtual host into idle animation mode

Casino Suite

A full multi-game casino with 8 games, all using the stream's currency system and featuring the bot as AI dealer.

Available Games

• Blackjack — Classic card game with split, double down, and insurance
• Video Poker — Jacks or Better with standard hand rankings
• Craps — Dice game with pass/don't pass betting
• Roulette — European-style wheel with inside and outside bets
• Horse Racing — Pick a horse and bet on the outcome
• Coin Flip — Simple heads/tails with multiplier
• Texas Hold'em — Full poker with community cards
• Slots — Configurable slot machine with payout tables

Example Commands

!blackjack 100      # Start a blackjack game with 100 coin bet
!slots 50           # Spin the slot machine for 50 coins
!roulette red 200   # Bet 200 coins on red in roulette

Trivia Engine

A full-featured trivia system with 9 game modes, 5 difficulty levels, and 16+ categories — complete with AI game show hosting and leaderboard tracking.

Game Modes

• Spontaneous: Quick single questions dropped into chat
• Rapid Fire: Multiple questions in fast succession
• Tournament: Bracket-style elimination rounds
• Countdown: Decreasing time pressure per question
• Team Battle: Teams compete for the highest combined score
• Game Show: Full AI-hosted game show with commentary and drama
• Marathon: Endurance mode — most correct answers wins
• Lightning: Ultra-fast response required
• Elimination: Last viewer standing wins

Configuration

Difficulty levels (Easy → Genius) control timer duration and score multipliers. Categories include General Knowledge, Science, History, Sports, Movies, Music, Gaming, Geography, Literature, Technology, Art, Animals, Food, Mythology, Language, and Politics.

Natural Language Parser

Viewers can interact with the bot using plain English instead of !commands. The AI extracts intent and maps it to registered plugin actions.

How It Works

• Intent Extraction: AI identifies what the viewer is trying to do from free-form text
• Action Mapping: Maps extracted intent to registered plugin commands
• Safety Framework: 5-tier safety system validates and sandboxes all AI-parsed commands
• Fallback: If intent extraction fails, falls back to normal AI chat response

Example

# Viewer types in chat:
"Can you play something chill?"
# Bot maps to: !request chill

"I want to play some blackjack"
# Bot maps to: !blackjack [default_bet]

"What's my balance?"
# Bot maps to: !balance

AI Charades

AI-powered charades with DALL-E image generation, category-based prompts, hint escalation, and currency rewards for correct guesses.

Features

• DALL-E Image Generation: Visual prompts generated per round
• 5 Categories: Movies, TV shows, phrases, bands, songs
• Hint Escalation: Subtle hint at 30s, stronger hint after — progressively easier
• Currency Rewards: Winners earn coins for correct guesses
• Stream Delay Buffer: 10-second buffer for fair guessing in delayed streams

Chat Commands

Currency System

The core cohost coins economy — tracks balances, processes transactions, awards bits/first-chatter bonuses, and provides a full admin panel with receipt ledger.

Features

• Cohost Coins: Stream currency used across games, music requests, and Channel Points
• First-Time Bonus: Automatic 100-coin reward for first-time chatters
• Bits Earning: Configurable multiplier converts cheers into coins
• Receipt Ledger: Every transaction logged with unique receipt numbers and source tracking
• Admin Panel: Manage user balances, view full transaction history at /currency/admin

Chat Commands

King of the Hill

Competitive gaming queue system with a live throne tracker, match scoring, viewer betting, AI screenshot analysis, and WebSocket overlay.

Features

• Queue Management: Players join with their playfield URL; queue is processed in order
• Betting System: Viewers bet coins on match outcomes with dynamic odds
• AI Score Reading: Optional AI screenshot analysis to auto-detect scores
• Leaderboard: Persistent win/loss/defense stats per player
• WebSocket Overlay: Live queue and king status on stream
• Admin Panel: Full queue management at /kingofthehill/admin

Chat Commands

Interactive Story

AI-generated choose-your-own-adventure stories driven by Twitch polls — each scene gets a DALL-E image, TTS narration, and dice rolls for dramatic outcomes.

Features

• Twitch Poll Choices: Chat votes on what happens next via native Twitch polls
• Per-Scene Images: 3 DALL-E images generated for each scene
• TTS Narration: AI narrates the story aloud with configurable voice
• Dice Roll System: d20 rolls with thresholds for dramatic success/failure moments
• Story Templates: Wild West, Sci-Fi, Fantasy, Horror, Detective starting points
• Story Archive: All stories saved and viewable at /interactive-story/stories

Chat Commands

Raffle System

Interactive raffle with a spinning wheel overlay, configurable entry limits, TTS winner announcements, and automatic periodic reminders.

Features

• Spinning Wheel Overlay: Animated wheel shown on stream when drawing a winner
• Entry Limits: Configurable max entries per raffle
• TTS Announcements: Winner announced aloud via TTS
• Auto-Reminders: Periodic chat reminders while raffle is open (every 20 min by default)
• Mod Controls: Add specific users, close/open raffle, draw winner from admin panel

Chat Commands

Shoutout System

Shouts out a streamer with a random clip from their channel, native Twitch shoutout API, and automatic game info lookup.

Features

• Clip Playback: Randomly selects and plays a clip from the target channel (up to 60s)
• Native Twitch Shoutout: Triggers the official Twitch /shoutout command alongside the clip
• Game Info Lookup: Fetches what game the streamer was last playing
• Cooldown: 1-minute per-user cooldown prevents spam
• Recent History: Admin panel tracks recent shoutouts at /shoutout/admin

Chat Commands

OBS Control

Full OBS remote control via WebSocket — manage scenes, sources, filters, stream state, and overlays from the admin panel without touching OBS.

Features

• Scene Management: Switch, create, and delete scenes
• Source Control: Toggle visibility, adjust volume, update settings per source
• Filter Management: Enable/disable and configure filters on any source
• Stream Controls: Start, stop, pause, and resume recording or streaming
• Overlay Installer: One-click setup for all Stream CoHost overlays at /obs/overlay-installer
• Screenshot Capture: Grab screenshots of any source programmatically
• Admin Panel: Full OBS dashboard at /obs/admin

Stream Manager

Create stream templates (title, game, tags) and apply them instantly via the admin panel — with optional Discord webhook notifications on each apply.

Features

• Stream Templates: Save and reuse title/game/tag combinations for common stream types
• One-Click Apply: Update Twitch channel info in one click without leaving the dashboard
• Discord Webhooks: Optionally post to Discord when a template is applied
• Usage Stats: Tracks how often each template is used
• Admin Panel: Manage all templates at /streamManager/admin

Moderation Tools

Twitch moderation system with ban/timeout execution, a warning system with escalation alerts, and a full audit log.

Features

• Ban & Timeout: Execute Twitch bans and timeouts directly from chat commands or admin panel
• Warning System: Issue warnings with severity levels; auto-alerts after 3+ warnings
• Whisper Notifications: Warned users receive a Twitch whisper with the reason
• Audit Log: Full history of all mod actions with timestamps and moderator attribution
• Admin Panel: User history lookup at /moderation/admin

Chat Commands

User Intro Media

Play a custom video or audio clip when a viewer first chats — per-user assignments with cooldowns, action chain support, and an intro request workflow.

Features

• Per-User Assignments: Each viewer can have their own custom entrance clip
• Default Fallback: A default clip plays for any viewer without a custom assignment
• Cooldown Control: Per-user cooldown (default 12 hours) prevents repeated playback
• Action Chain Support: Trigger full timer action chains as intros, not just media
• Intro Request Queue: Viewers can request a custom intro via Channel Points — mods approve via admin panel
• Bot Filtering: Known bots automatically skipped
• Admin Panel: Manage all assignments at /userIntroMedia/admin

Chat Commands

Analytics Dashboard

Real-time health monitoring and analytics across chat, currency, OpenAI usage, games, plugins, and system performance — all in one dashboard.

What's Tracked

• Health Monitoring: WebSocket latency, uptime, reconnections, and error rates
• Chat Analytics: Top chatters, most-used commands, message volume over time
• Currency Tracking: Top earners/spenders, transaction volume, economy health
• OpenAI Usage: API call counts, token usage, cost estimation
• Game Analytics: Play counts, durations, outcomes per game type
• Plugin Performance: Per-plugin execution time and success rates
• System Metrics: CPU, memory, active connections

Dashboard available at /analytics/dashboard. Health data retained 24 hours; media and game events retained 7 days.

Persona & Mood System

The bot maintains a dynamic emotional state and personality — mood shifts based on chat events, decays toward neutral over time, and influences how the AI responds.

How It Works

• Numeric Mood Scale: -100 (very negative) to +100 (very positive) with continuous tracking
• 13+ Special States: Named moods (happy, sarcastic, hype, tired, etc.) that override numeric mood
• Mood Decay: Automatically reverts toward neutral with a configurable half-life (default 90 minutes)
• Personality Traits: Top 4 active traits shape AI responses alongside mood
• Event-Driven Shifts: Game wins/losses, currency events, chat interactions all affect mood
• Per-User Moods: Each viewer also has a mood profile that influences how the bot interacts with them

Chat Commands

Channel Points

Link Twitch Channel Point rewards to bot commands, timer action chains, or built-in handlers — managed entirely through the admin panel.

Features

• Reward Mapping: Bind any Channel Point reward to a bot command or action chain
• Built-in Handlers: Random song requests, overlay messages, queue additions, mood changes
• User Input Support: Redemptions that require viewer-typed input pass it to the linked command
• Admin Panel: Manage all reward mappings at /channelPoints/admin

Admin Control

Central dashboard for bot mode switching, active conversation monitoring, rate limit management, and emergency controls.

Bot Modes

• Normal: All features enabled
• Chat Only: Commands disabled for regular viewers; mods bypass
• Quiet: 50% response rate reduction
• Maintenance: Admin-only responses

Features

• Live Conversation Monitor: View last 100 conversations in real time
• Emergency Stop: Immediately halt all bot responses
• Quick Blacklist Actions: Timeout, drunk-mode, chat-only, or cooldown a user in one click
• Bot Restart: Restart via PM2 without leaving the dashboard
• Admin Dashboard: Available at /admin-control/dashboard

Chat Commands

Timer & Actions

Automated event chains with sequential steps, conditional logic, variable substitution, and database persistence — the backbone of scheduled stream events.

Features

• Action Chains: Build multi-step sequences: chat messages, TTS, OBS scene changes, media playback, delays
• Conditional Logic: If/else branching based on stream state or variable values
• Variable Substitution: Dynamic values (viewer name, coin balance, current game) injected into any step
• Channel Points Triggers: Chains can be bound to Channel Point redemptions
• Input Listeners: Chains can pause and wait for viewer chat input before continuing
• Database Persistence: All chain definitions stored in SQLite and survive restarts

Plugin Development

Learn how to create custom plugins for Stream CoHost using our comprehensive API.

Plugin Structure

All plugins follow a standardized structure for consistency and maintainability:

// plugins/myPlugin/index.js
module.exports = {
    name: 'myPlugin',
    dependencies: ['currency', 'openai'],  // optional

    async init(bot) {
        // Basic setup — do NOT access other plugins here
        // Only safe to use: bot.db, bot.config, bot.app (routes)
        bot.app.get('/api/myplugin/status', (req, res) => {
            res.json({ status: 'active' });
        });
    },

    async lateInit(bot) {
        // All plugins are ready — register services and cross-plugin calls here
        bot.services.myPlugin = {
            doSomething: () => { /* ... */ }
        };

        // Register beforeOpenAI hook (non-blocking)
        if (bot.hooks?.register) {
            bot.hooks.register('beforeOpenAI', async (context) => {
                // Inject extra context before each AI call
                context.extra = 'my plugin context';
            });
        }
    },

    commands: {
        mycommand: async (bot, msg, args) => {
            await bot.say(msg.channel, `Hello, ${msg.username}!`);
        }
    }
};

Available APIs

API Reference

Complete reference for all available APIs and methods in Stream CoHost.

Bot Core API

bot.registerCommand('!hello', async (context) => {
    return { success: true, response: 'Hello World!' };
});

Memory API