the pluggable python framework for IRC bots and Twitch bots

View the Project on GitHub archangelic/pinhook


Supported Python versions Package License PyPI package format Package development status With love from

The pluggable python framework for IRC bots and Twitch bots


Pinhook can be installed from PyPI:

pip install pinhook

Creating an IRC Bot

A pinhook bot can be initialized using the command line tool pinhook with a config file, or by importing it into a python file to extend the base class.

From Config File

Pinhook supports configuration files in YAML, TOML, and JSON formats.

Example YAML config:

nickname: "ph-bot"
server: ""
    - "#foo"
    - "#bar"

Required configuration keys:

Optional keys:

Once you have your configuration file ready and your plugins in place, you can start your bot from the command line:

pinhook config.yaml

Pinhook will try to detect the config format from the file extension, but the format can also be supplied using the --format option.

$ pinhook --help
Usage: pinhook [OPTIONS] CONFIG

  -f, --format [json|yaml|toml]
  --help                         Show this message and exit.

From Python File

To create the bot, just create a python file with the following:

from import Bot

bot = Bot(
    channels=['#foo', '#bar'],

This will start a basic bot and look for plugins in the ‘plugins’ directory to add functionality.

Optional arguments are:

Creating a Twitch Bot

Pinhook has a baked in way to connect directly to a twitch channel

from import TwitchBot

bot = TwitchBot(

This function has far less options, as the server, port, and ssl are already handled by twitch.

Optional aguments are:

These options are the same for both IRC and Twitch

Creating plugins

There are two types of plugins, commands and listeners. Commands only activate if a message starts with the command word, while listeners receive all messages and are parsed by the plugin for maximum flexibility.

In your chosen plugins directory (“plugins” by default) make a python file with a function. You use the @pinhook.plugin.command decorator to create command plugins, or @pinhook.plugin.listener to create listeners.

The function will need to be structured as such:

import pinhook.plugin

def test_plugin(msg):
    message = '{}: this is a test!'.format(msg.nick)
    return pinhook.plugin.message(message)

The function will need to accept a single argument in order to accept a Message object from the bot.

The Message object has the following attributes:

It also contains the following IRC functions:

You can optionally set a command to be used only by ops

The function will need to be structured as such:

@pinhook.plugin.command('!test', ops=True, ops_msg='This command can only be run by an op')
def test_plugin(msg):
    return pinhook.plugin.message('This was run by an op!')

The plugin function can return one of the following in order to give a response to the command:


There are some basic examples in the examples directory in this repository.

Here is a list of live bots using pinhook: