Files

user bf45abcbad feat: initial implementation

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

- IRC protocol: message parsing, formatting, async TCP/TLS connection
- Plugin system: @command and @event decorators, file-based loading
- Bot orchestrator: connect, dispatch, reconnect, nick recovery
- CLI: argparse entry point with TOML config
- Built-in plugins: ping, help, version, echo
- 28 unit tests for parser and plugin system

2026-02-15 00:37:31 +01:00

1.5 KiB

Raw Blame History

Debugging

Verbose Mode

derp --verbose

Shows all IRC traffic:

>>> NICK derp
>>> USER derp 0 * :derp IRC bot
<<< :server 001 derp :Welcome
>>> JOIN #test

Log Levels

Set in config/derp.toml:

[logging]
level = "debug"    # debug, info, warning, error

Common Issues

Connection refused

ERROR derp.irc  connection lost: [Errno 111] Connection refused

Check host and port in config
Verify TLS setting matches port (6697 = TLS, 6667 = plain)
Test connectivity: nc -zv <host> <port>

Nickname in use

The bot appends _ to the nick and retries automatically. Check logs for:

<<< :server 433 * derp :Nickname is already in use
>>> NICK derp_

TLS certificate errors

If the server uses a self-signed certificate, you may need to adjust the SSL context. Currently uses system default CA bundle.

Plugin load failures

ERROR derp.plugin  failed to load plugin: plugins/broken.py

Check plugin file for syntax errors: python -c "import plugins.broken"
Ensure handlers are async def
Check imports (from derp.plugin import command, event)

No response to commands

Verify prefix in config matches what you type
Check that the plugin is loaded (look for "loaded plugin" in verbose output)
Ensure the bot has joined the channel

Testing IRC Connection

# Test raw IRC (without the bot)
openssl s_client -connect irc.libera.chat:6697
# Then type: NICK testbot / USER testbot 0 * :test

1.5 KiB Raw Blame History