kickforge 0.2.1

The open-source toolkit for interactive Kick.com streams — bots, game integrations, overlays & clip automation.

🔥 KickForge

The open-source toolkit for interactive Kick.com streams.

Build bots, connect games, automate clips, and create real-time overlays — all with Python.

---

What is KickForge?

KickForge is a modular Python toolkit that lets you build interactive experiences on Kick.com. It handles the boring parts (OAuth, webhooks, API calls) so you can focus on the fun parts (making your stream chaotic, engaging, and profitable).

Packages

Package	What it does
kickforge-core	OAuth 2.1, webhook server, event bus, REST API client
kickforge-bot	Chat commands, loyalty/XP, moderation, polls, plugins
kickforge-gsi	Game integrations — CS2, Minecraft, GTA via RCON/API
kickforge-clip	Auto-detect hype moments, cut clips, export to Shorts
kickforge-overlay	Real-time OBS widgets via WebSocket

Quick Start

pip install kickforge

Then scaffold a project and run:

kickforge init my-bot
cd my-bot
# Edit config.yaml with your Kick Dev credentials
python bot.py

30-Second Bot

from kickforge_core import KickApp

app = KickApp(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)

@app.on("chat.message.sent")
async def on_chat(event):
    if event.message == "!ping":
        await app.say("pong! 🏓")

@app.on("kicks.gifted")
async def on_gift(event):
    await app.say(f"🔥 {event.gifter_username} sent {event.kicks_amount} kicks!")

app.run(port=8420)

Interactive Gaming (CS2 Example)

from kickforge_core import KickApp

app = KickApp(client_id="...", client_secret="...")

@app.on("kicks.gifted")
async def on_gift(event):
    if event.kicks_amount >= 50:
        # Send RCON command to your CS2 server
        execute_rcon("sv_gravity 200")  # Low gravity!
        await app.say(f"🪐 {event.gifter_username} activated LOW GRAVITY!")

app.run()

See examples/cs2_interactive.py for a full interactive CS2 setup with tier-based actions.

Architecture

Kick.com ──webhook──▶ KickForge Core ──events──▶ Your Code
                           │                        │
                      Event Bus              Game Adapters
                      REST API               OBS Overlays
                      Auth Manager           Clip Pipeline

Everything flows through the Event Bus. You register handlers with @app.on("event_type") and KickForge routes events to your code. No polling, no WebSocket management, no token refresh headaches.

Supported Kick Events

Event	Trigger
chat.message.sent	Someone sends a chat message
channel.followed	New follower
channel.subscription.new	New subscriber
channel.subscription.renewal	Sub renewal
channel.subscription.gifts	Gift subs
kicks.gifted	Kicks (coins) gifted
livestream.status.updated	Stream goes live/offline
moderation.banned	User banned

Bot Setup

To let your bot send chat messages (not just listen), you need a user access token with chat:write scope. KickForge has a built-in OAuth flow that handles this in under a minute.

1. Register the callback URL in your Kick Dev App

Go to kick.com/settings/developer and add this to your app's Redirect URIs:

http://localhost:8421/auth/callback

2. Run the auth flow

kickforge auth

This will:

• Start a tiny local server on port 8421
• Open your browser to Kick's authorize page (with PKCE)
• After you click Approve, save the token to ~/.kickforge/tokens.json

You'll see:

Token saved to /Users/you/.kickforge/tokens.json
Your bot can now send chat messages.

3. Run your bot

python examples/minimal_bot.py

Now the bot both listens (via Pusher WebSocket) AND writes to chat. Tokens auto-refresh in the background, so you only need to run kickforge auth once.

Troubleshooting: If chat sending still returns 401, make sure:

• Your Kick Dev App has chat:write scope enabled
• You clicked Approve in the browser (not Deny)
• The callback URL in the Kick dashboard exactly matches http://localhost:8421/auth/callback

Run kickforge auth again to re-authorize at any time.

---

First Real Test

End-to-end in 5 minutes: wire up KickForge to the real Kick API and see a live event arrive.

1. Install and configure

pip install kickforge
cp .env.example .env

Edit .env with your Kick Developer credentials (get them at kick.com/settings/developer):

KICK_CLIENT_ID=your_client_id_here
KICK_CLIENT_SECRET=your_client_secret_here
KICK_BROADCASTER_ID=your_broadcaster_user_id_here

Your KICK_BROADCASTER_ID is the numeric user ID of the channel you want to receive events for. You can find it in your Kick Developer dashboard or by calling GET /public/v1/channels?slug=your_channel_name.

2. Start ngrok first

ngrok http 8420

Copy the HTTPS forwarding URL (e.g. https://a1b2c3.ngrok-free.app).

3. Set the webhook URL in Kick

Go to your Kick Developer App settings. Paste your ngrok URL with /webhook appended as the Webhook URL:

https://a1b2c3.ngrok-free.app/webhook

This is configured in the Kick dashboard, not in your .env file. Kick needs to know where to send events, and this is how you tell it.

4. Subscribe to events

python examples/subscribe_events.py

This tells the Kick API which events you want to receive. You should see output like:

Subscribing to 5 events for broadcaster 123456...
Done. Your webhook server will now receive these events.

5. Start the bot

python examples/minimal_bot.py

You should see the KickForge banner and "Waiting for Kick events...".

6. Send a test message

Open your Kick channel in a browser and type !ping in chat. Back in your bot terminal you should see:

Received webhook: type=chat.message.sent subscription=...
Executed command: !ping by your_username

The bot replies "pong!" in chat. You're live.

---

Setup Webhook (Development)

KickForge needs a public URL for Kick to send webhooks to. During development:

# Terminal 1: Run your bot
python bot.py

# Terminal 2: Expose to internet
ngrok http 8420

# Copy the ngrok URL (e.g. https://abc123.ngrok.io)
# Set it in Kick Dev settings: https://kick.com/settings/developer
# Webhook URL: https://abc123.ngrok.io/webhook

Project Structure

kickforge/
├── kickforge_core/     # OAuth, webhooks, events, API
├── kickforge_bot/      # Chat bot framework
├── kickforge_gsi/      # Game integrations (CS2, MC, GTA)
├── kickforge_clip/     # Auto clip pipeline
├── kickforge_overlay/  # OBS widgets
├── examples/           # Working examples
├── tests/              # Test suite
└── docs/               # Documentation

Contributing

KickForge is open source (MIT). Contributions welcome!

• 🐛 Found a bug? Open an issue
• 💡 Got an idea? Start a discussion
• 🔧 Want to add a game adapter? See the adapter guide

Roadmap

• Core engine (OAuth, webhooks, events, API)
• CLI scaffolding (kickforge init)
• Bot framework (commands, loyalty, moderation, polls, plugins)
• CS2 GSI adapter (read-only + RCON write)
• Minecraft RCON adapter
• Generic HTTP adapter (FiveM, custom games)
• Auto-clip pipeline (heat detection, FFmpeg, Shorts formatter)
• OBS overlay widgets (6 widgets via WebSocket)
• PyPI release v0.1.0
• Documentation site

License

MIT — do whatever you want with it. Build something cool.

---

Built by Yargitay | GitHub | PyPI — streaming on Kick, building tools for streamers.