KfChatDotNet/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

KfChatDotNet is a C# .NET 10.0 chat bot for KiwiFarms (Sneedchat) with extensive third-party integrations. The solution consists of three projects:

• KfChatDotNetWsClient: WebSocket client library for KiwiFarms chat communication
• KickWsClient: WebSocket client library for Kick platform integration
• KfChatDotNetBot: Main bot application with command handling and service integrations

Build and Development Commands

# Build the entire solution
dotnet build

# Build in Release mode
dotnet build -c Release

# Run the bot
dotnet run --project KfChatDotNetBot

# Clean build artifacts
dotnet clean

# Restore NuGet packages
dotnet restore

Database Management

The bot uses Entity Framework Core with SQLite (db.sqlite).

# Add a new migration (from solution root)
dotnet ef migrations add <MigrationName> --project KfChatDotNetBot

# Update database to latest migration
dotnet ef database update --project KfChatDotNetBot

# Remove the last migration
dotnet ef migrations remove --project KfChatDotNetBot

# View migration SQL
dotnet ef migrations script --project KfChatDotNetBot

Migrations run automatically on startup via Program.cs.

Architecture

Message Flow

1. ChatClient (KfChatDotNetWsClient/ChatClient.cs): WebSocket connection and event emission

   • Connects to KiwiFarms WebSocket endpoint
   • Parses incoming packets and emits typed events
   • Handles reconnection logic and cookie management

2. ChatBot (KfChatDotNetBot/ChatBot.cs): Core bot orchestration

   • Subscribes to ChatClient events
   • Manages sent message tracking and auto-deletion
   • Handles GambaSesh presence detection
   • Coordinates with BotServices for external integrations

3. BotCommands (KfChatDotNetBot/Services/BotCommands.cs): Command routing

   • Uses reflection to discover all ICommand implementations
   • Matches incoming messages against command regex patterns
   • Enforces rate limits, permissions, and timeouts
   • Filters based on user rights and Kasino bans/exclusions

4. ICommand Implementations (KfChatDotNetBot/Commands/): Individual command handlers

   • Each command defines regex patterns for matching
   • Commands specify required user rights and rate limits
   • Commands can be marked with attributes (NoPrefixRequired, KasinoCommand, WagerCommand, AllowAdditionalMatches)

Command System

All commands implement ICommand interface:

• Patterns: List of regex patterns for command matching
• HelpText: Help text shown to users (null to hide from help)
• RequiredRight: Minimum user permission level
• Timeout: Command execution timeout
• RateLimitOptions: Rate limiting configuration
• RunCommand(): Async method that executes the command

Command attributes:

• [NoPrefixRequired]: Command matches without requiring ! prefix
• [AllowAdditionalMatches]: Continue processing after this command matches
• [KasinoCommand]: Requires Kasino to be enabled, enforces bans
• [WagerCommand]: Enforces self-exclusions for gambling addicts

Settings System

Settings are stored in the database (not config files) via SettingsProvider:

• SettingsProvider.GetValueAsync(key) - Get a single setting
• SettingsProvider.GetMultipleValuesAsync(keys) - Get multiple settings efficiently
• SettingsProvider.SetValueAsync(key, value) - Update a setting
• Built-in keys defined in BuiltIn.Keys static class
• Migration from legacy config.json happens automatically on startup

Service Integrations

BotServices (KfChatDotNetBot/Services/BotServices.cs) initializes and manages connections to external services:

• Discord: Message relaying and bot presence
• Twitch: Stream status monitoring and GraphQL API
• Kick: WebSocket connection for stream events
• Gambling sites: Rainbet, Shuffle, Howlgg, Chipsgg, Clashgg, BetBolt, Yeet
• Stream platforms: DLive, PeerTube, Owncast, YouTube
• Kasino: Internal gambling system with rain, mines, limbo, coinflip

Each service is implemented as a separate class in KfChatDotNetBot/Services/.

Message Tracking

ChatBot.SendChatMessage() and ChatBot.SendChatMessageAsync() return a SentMessageTrackerModel:

• Tracks message status (WaitingForResponse, ResponseReceived, Lost, NotSending)
• Provides message ID for editing/deletion
• Measures round-trip delay
• Supports auto-deletion after a specified TimeSpan
• Handles message replay after disconnection

Database Schema

The ApplicationDbContext manages these entities:

• Users: KiwiFarms users with permissions
• Gamblers: Kasino users with balance and stats
• Transactions: Kasino transaction history
• Wagers: Active and historical bets
• Exclusions: Self-exclusion periods
• Perks: Gambler perks (e.g., reduced house edge)
• Settings: Bot configuration
• Images: Uploaded image metadata
• UsersWhoWere: User activity timestamps (join/part/message)
• Various third-party service data tables (HowlggBets, RainbetBets, etc.)

Important Patterns

Async/Await Conventions

The codebase has inconsistent async patterns:

• Some methods expose both sync and async versions (e.g., SendChatMessage() and SendChatMessageAsync())
• Disconnect() is intentionally synchronous with a separate DisconnectAsync() method
• Avoid changing existing sync/async signatures without careful consideration

GambaSesh Detection

GambaSesh is another bot that the bot avoids conflicting with:

• ChatBot.GambaSeshPresent tracks his presence
• Messages are suppressed by default when he's present (unless bypassSeshDetect=true)
• Presence is detected via user join events and messages
• BotServices.TemporarilyBypassGambaSeshForDiscord exists for special cases

Length Limits

Sneedchat enforces a 1023-byte message limit:

• SendChatMessage() accepts LengthLimitBehavior enum: TruncateNicely, TruncateExactly, RefuseToSend, DoNothing
• Use string.Utf8LengthBytes() extension method to check length
• Use string.TruncateBytes(limit) extension method to truncate safely

Session Management

The bot handles KiwiFarms authentication via cookies:

• KfTokenService manages login and cookie refresh
• On 203 status code or "cannot join room" errors, cookies are refreshed
• Cookies are persisted to the database
• Bot can operate in "guest mode" with no cookies

Common Tasks

Adding a New Command

1. Create a new class in KfChatDotNetBot/Commands/ that implements ICommand
2. Define regex patterns in the Patterns property
3. Implement RunCommand() method with command logic
4. Set RequiredRight, Timeout, RateLimitOptions, and HelpText
5. Add attributes if needed: [NoPrefixRequired], [KasinoCommand], etc.
6. The command will be auto-discovered via reflection on next startup

Adding a New Service Integration

1. Create a new class in KfChatDotNetBot/Services/
2. Add initialization method to BotServices.InitializeServices()
3. Add corresponding settings keys to BuiltIn.Keys
4. If the service needs WebSocket or periodic tasks, follow existing patterns (PeriodicTimer, WebsocketClient)

Modifying the Database Schema

1. Update the relevant DbModel class in KfChatDotNetBot/Models/DbModels/
2. Add/update the DbSet property in ApplicationDbContext.cs
3. Generate a migration: dotnet ef migrations add <Name> --project KfChatDotNetBot
4. Migration runs automatically on next bot startup

Sending Messages to Chat

// Synchronous
var tracker = _bot.SendChatMessage("Hello!");

// Asynchronous
var tracker = await _bot.SendChatMessageAsync("Hello!");

// Bypass GambaSesh detection
_bot.SendChatMessage("Important message", bypassSeshDetect: true);

// Auto-delete after 5 seconds
await _bot.SendChatMessageAsync("Temporary message", autoDeleteAfter: TimeSpan.FromSeconds(5));

// Wait for the message to be echoed by the server
if (await _bot.WaitForChatMessageAsync(tracker, TimeSpan.FromSeconds(10)))
{
    // Message was successfully sent, tracker.ChatMessageId is now available
}

Dependencies

Key NuGet packages:

• Websocket.Client: WebSocket client used throughout
• Microsoft.EntityFrameworkCore.Sqlite: Database ORM
• NLog: Logging framework
• Humanizer.Core: Human-readable text formatting
• SixLabors.ImageSharp: Image manipulation for meme generation
• StackExchange.Redis: Redis caching
• FlareSolverrSharp: Cloudflare bypass
• HtmlAgilityPack: HTML parsing
• Nerdbank.GitVersioning: Automatic versioning from git tags

Testing

There are currently no automated tests in this repository. Manual testing is performed by running the bot.

Logging

NLog configuration is in KfChatDotNetBot/NLog.config. The bot logs extensively:

• Debug: Detailed packet information, message processing steps
• Info: User joins/parts, sent messages, state changes
• Error: Exceptions, disconnections, failed operations

Code Style Notes

• The codebase uses explicit null checks and nullable reference types
• Extensive use of LINQ for data queries
• Some deliberately provocative comments and language (see Program.cs license header)
• Privacy is explicitly not a concern - data is logged freely
• Performance optimizations include "BUY MORE RAM" philosophy (unlimited message tracking)