Created: 2011-09-02 10:16
Updated: 2016-04-19 17:17


For list of commands offered by the bot, see help page.


seejoo is an IRC utility bot coded in Python and built upon the Twisted networking library. Its main highlight is the extensible architecture: in most cases, new functionality can be added by implementing custom plugins, rather than hacking the core code. This approach also allows for customizing the specific bot instance to meet one'a particular needs.

The name seejoo comes from the lojban word sidju which roughly means 'to help'.


For updating convenience it's recommended to use with develop parameter:

$ git clone git://
$ cd seejoo
$ sudo ./ develop

This allows to simply git pull changes without having to run the script again.

Note: You will likely need to sudo the installation. If you are using a shell account and don't have root access, you can use virtualenv to create a personal copy of Python interpreter.


Starting the bot as a simple as running:

$ seejoo

However, you will likely want to customize the bot by providing a YAML configuration file:

$ seejoo --config seejoo.yaml

See the attached example_config.yaml for supported config parameters.

Creating your own plugins

Plugins are means for extending the bot's functionality. They are small programs which are driven by the IRC-related events, such as someone joining a channel, saying something, changing channel's mode, and so on. Plugins get notified about those events and can respond to them.

From the Python point of view, plugins are simple callables which get called when an event happens. The simplest way to write a plugin is to subclass the seejoo.ext.Plugin class, which is shown at the example below:

from seejoo.ext import Plugin, plugin
from seejoo.util import irc
class HelloResponder(Plugin):
    def message(self, bot, channel, user, message, msg_type):
        if not channel: return # Discarding non-channel messages
        # if user says something which resembles a greeting, respond to it
        msg = message.lower()
        if msg.startswith("hello") or msg.startswith("hi"):
            nick = irc.get_nick(user)
            response = "Hello %s!" % nick
            irc.say(bot, channel, response)

Note that the class is decorated to with @plugin decorator. This is required as in principle, plugins could also be normal functions.

For the list of interesting events you could handle in your plugin, see the definition of seejoo.ext.Plugin class.

Cookies help us deliver our services. By using our services, you agree to our use of cookies Learn more