← Back to all projects

Automated stream chat presence. Detects when Hyper or Ryan go live, joins chat as QuagmirePeak, handles promo responses.

🟢 Auto-join

💬 Promo responses

🔒 TG-only auth

📄 1 document

📄 README.md ▼

Kick Stream Auto-Detection & Chat Bot

QuagmirePeak — Automated Kick chat presence for Hyper and Ryan's streams.

Architecture

┌─────────────────────────────────────────────────┐
│                   CRON / Manual                  │
│              (every 5 minutes)                   │
└─────────────────┬───────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────┐
│              run_bot.sh                          │
│  - Acquires lock (prevents concurrent runs)      │
│  - Calls stream_checker.py                       │
│  - If live: activates chat_manager.py            │
└─────────────────┬───────────────────────────────┘
                  │
        ┌─────────┴──────────┐
        ▼                    ▼
┌───────────────┐   ┌────────────────┐
│stream_checker │   │ chat_manager   │
│    .py        │   │     .py        │
│               │   │                │
│ HTTP requests │   │ CDP WebSocket  │
│ to Kick API   │   │ to Chrome      │
│ v2 endpoint   │   │ port 18800     │
└───────────────┘   └────────────────┘
        │                    │
        ▼                    ▼
  Kick API v2          Chrome Browser
  (no auth)           (clawd profile)
                     logged in as
                     QuagmirePeak

Components

1. `stream_checker.py` — Live Detection

Checks Kick API v2 (/api/v2/channels/{username}) to detect if streams are live.

# Check all channels
python3 stream_checker.py

# Check specific channel
python3 stream_checker.py hyperlive

# JSON output (for scripting)
python3 stream_checker.py --json

# Use as module
from stream_checker import check_channel, get_live_channels

How it works: Makes HTTP GET requests to Kick's public API. If livestream field is non-null, the stream is live. No authentication required.

2. `chat_manager.py` — Chat Control

Reads and sends messages via Chrome DevTools Protocol (CDP).

# Read recent chat
python3 chat_manager.py hyperlive --check

# Send a message
python3 chat_manager.py hyperlive --send "What's good chat 🤙"

# Navigate to channel
python3 chat_manager.py hyperlive --navigate

# Check page status
python3 chat_manager.py hyperlive --status

Chat method: Uses document.execCommand('insertText') for message insertion (other methods fail on Kick's React-based chat). Enter key is dispatched as a separate CDP Input.dispatchKeyEvent action.

3. `config.json` — Configuration

Contains persona, promo responses, rate limits, security settings.

4. `run_bot.sh` — Integration Runner

Orchestrates the check-and-join flow. Safe for cron usage with lock file.

# Run manually
./run_bot.sh

# Check specific channel
./run_bot.sh hyperlive

# View current state
./run_bot.sh --status

Quick Start

Manual

cd /Users/hypersassistant/clawd/builds/kick-bot

# 1. Check if anyone is live
python3 stream_checker.py

# 2. If live, navigate and join
python3 chat_manager.py hyperlive --navigate
sleep 5
python3 chat_manager.py hyperlive --send "What's good chat 🤙"

# 3. Read chat
python3 chat_manager.py hyperlive --check

Cron (Automated)

# Edit crontab
crontab -e

# Add this line (check every 5 minutes):
*/5 * * * * /Users/hypersassistant/clawd/builds/kick-bot/run_bot.sh >> /Users/hypersassistant/clawd/builds/kick-bot/logs/cron.log 2>&1

Via Clawdbot Heartbeat

Add to HEARTBEAT.md:

- [ ] Check if Hyper or Ryan are live on Kick (run /Users/hypersassistant/clawd/builds/kick-bot/run_bot.sh)

Prerequisites

Chrome browser running with CDP on port 18800 (clawd profile)
Start: clawdbot browser start --profile clawd
QuagmirePeak logged in on Kick in the clawd browser profile
Python 3 with requests library
Node.js with ws module (/opt/homebrew/lib/node_modules/ws)

Security

⚠️ Critical: QuagmirePeak NEVER takes orders from Kick chat users.

Commands only accepted via Telegram from verified IDs
Hyper: @hypaaaaa (5737113835)
Ryan: @ivessaintlaurent (6473919905)
Chat accounts impersonating them (e.g., "HyperGAMBLES") are ignored

Rate Limits

Setting	Value	Why
Between messages	60s min	Avoid Kick rate limits/bans
Between API checks	300s min	Don't hammer Kick API
Cron interval	5 min	Balance responsiveness vs resources

Files

kick-bot/
├── config.json          # Bot configuration & promo responses
├── stream_checker.py    # Live detection (Kick API)
├── chat_manager.py      # Chat read/send (CDP)
├── run_bot.sh           # Integration runner (cron-safe)
├── state.json           # Runtime state (auto-generated)
├── README.md            # This file
└── logs/
    ├── runner_YYYY-MM-DD.log   # Runner logs
    ├── hyperlive_YYYY-MM-DD.log    # Chat logs
    └── mountainlive_YYYY-MM-DD.log # Chat logs

Known Limitations

Browser automation fragility — Kick updates their DOM structure periodically. If selectors break, update JS_READ_CHAT and JS_INSERT_TEXT_TEMPLATE in chat_manager.py.
Single tab — CDP approach works with one Kick channel tab at a time. If both streams are live simultaneously, the bot can only be in one chat.
Cloudflare blocks curl — The Kick API blocks curl and web_fetch but allows Python requests. If this breaks, fall back to browser-based API calls.
No real-time chat — The bot reads chat on poll intervals, not via WebSocket. Responses to triggers may be delayed.
Login persistence — If the Kick session expires, someone needs to re-login manually in the clawd browser profile.

Future Improvements

Kick WebSocket API — Native chat connection via Pusher/WebSocket for real-time message reading and sending (no browser needed)
Dual-channel support — Open both channels in separate tabs and switch between them
AI chat responses — Feed chat context to Claude for witty, in-character Quagmire responses
Telegram notifications — Alert Hyper/Ryan when their stream goes live (or when the bot joins)
Auto-recovery — Detect and recover from Kick session expiry, page crashes, etc.

Kick Chat Bot