Casul IRC Engine

Python implementation of IRC engine for bots


This is an IRC Engine, meaning, it will perform all of the connections, user communication, and message handling events for your IRC bot. Your custom IRC bot commands will live as modules of this engine - callable by your endusers.

Therefore, code that is found within the engine itself should only reflect generic actions that will be relevant to most custom IRC bots. Keep this in mind when submitting Pull Requests.


$> git clone


  1. Python 2.7
  2. pip Python Package Manager (pip Installation Guide)

Developing for Casul IRC Engine

It is the end-goal that will be in such a state that it will not require any changes by developers, but simply adding new modules and modifying configuration settings will allow any features required. So you're probably interested in adding new functionality to this bot. The great news is, you only need to drop in 1 file, which is logically separated from the rest of the bot, and you're golden! Let's read more about how to accomplish this.

Adding a new module

The beauty of this bot implementation is that it will automatically look for new modules at startup. The name of your file will be the keyword command associated with calling your code. So, if you have !uptime as your desired command, you'll add an module in the casul_cmds folder. If you'd rather specify your command name, you can name your module whatever you'd like, and specify a cmds property of your module which will contain a list of all callable handles to your module.

Module Requirements

For a standard user-requested module, you only need to maintain a function with signature:

def run(sender, components=None):
  # your code here

If you need code to run as the bot is starting (before connecting to IRC), you can optionally include an init function. Similarly, if you want the !help module to expose any documentation you want to provide, you can optionally include that endpoint too.

def init(sender, components=None):
  # your startup code here

def help(components=None):
  return ['Usage: !module <args>', 'Second line of help here.']

If you want your module to execute for multiple commands (rather than just keyword of file), you can add a parameter to your module listing all callable handles.


cmds = ['asdf', 'hello'] # this module is callable by !asdf, and !hello

So, putting it all together, a sample module will look like this:


cmds = ['time'] # callable by !time, rather than default module name !curr_time

def init(sender, components=None):
  pass # I don't need to initialize anything. This method isn't even required.
def run(sender, components=None):
  return time.ctime()
def help(components=None):
  return ['Usage: !time', 'Action: Will return current time.']

Task Requirements

If you want an automated task to run at scheduled intervals, you can create a python module in the casul_tasks folder to achieve this. Here, you are required to take one extra step of including your time interval (in seconds) as a part of your Python module. Here's a quick example.


from datetime import datetime

interval = 30 # every 30 seconds run this package
day = 0

def init(sender, components=None):
  global day
  day =

def run(sender, components=None):
  global day
  now =
  if now != day:
    day = now
    sender.irc.CHAN_BROADCAST("It's a new day!")


You will want to modify which stores runtime information such as which channels to connect to, hostname, nick, etc. If you are interested in the twitch_stream module, it has its own .ini file you'll want to look at.

Running Casul IRC Engine

$> python


This engine has been modified with great ideas from paullik's IRC-Bot, of which Casul IRC Engine has its extensibility & config modeled.


Please see the LICENSE file to read about the MIT License.