derp

Asyncio IRC bot for Python 3.11+ with a decorator-based plugin system. Zero external dependencies.

Quick Start

git clone <repo> ~/git/derp && cd ~/git/derp
make install
# Edit config/derp.toml with your server details
make run

Features

• Async IRC over plain TCP or TLS
• Plugin system with @command and @event decorators
• TOML configuration with sensible defaults
• Auto reconnect, nick recovery, PING/PONG handling
• Built-in commands: !ping, !help, !version

Configuration

Edit config/derp.toml:

[server]
host = "irc.libera.chat"
port = 6697
tls = true
nick = "derp"

[bot]
prefix = "!"
channels = ["#test"]
plugins_dir = "plugins"

Writing Plugins

Create a .py file in plugins/:

from derp.plugin import command, event

@command("greet", help="Say hello")
async def cmd_greet(bot, message):
    await bot.reply(message, f"Hello, {message.nick}!")

@event("JOIN")
async def on_join(bot, message):
    if message.nick != bot.nick:
        await bot.send(message.target, f"Welcome, {message.nick}")

Commands

Command	Description
make install	Create venv and install
make test	Run test suite
make lint	Lint with ruff
make run	Start the bot
make link	Symlink to ~/.local/bin/

Documentation

• Installation
• Usage Guide
• Cheatsheet
• Debugging

License

MIT