Skip to content


Repository files navigation


A bot that logs user conversations on IRC and helps generate statistics for them using pisg.


This bot is tested on Ruby 2.1.0 but should work for earlier versions. If you do not have Bundler installed, run gem install bundler. Then, do bundle install in this directory to install the gems needed.

You will also need a pisg installation pointed to the pisg.cfg file that is auto-generated in this directory. This pisg instance will do all the work of generating the statistics from the log files. You should set it up to run on a regular basis to regenerate the stats using cron.


Prior to starting the bot, you must configure it. Copy settings.example.json to settings.json and open it in your text editor. Follow this table to configure the bot.

Key Type Description
server string Hostname of the IRC server to connect to
port int Port of the IRC server to connect to
ssl boolean Use SSL when connecting?
nickserv object nick and pass are the credentials used to log your bot into NickServ using IDENTIFY pass. If pass is empty, the bot will not log in to NickServ.
locations object logs is the path to the logs directory, stats is the path to where pisg should output the generated statsto, and url is the full HTTP URL of the root path to where a web server serves the contents of stats.
identity object nick, ident, and realname used when connecting.
oper object Optional. user and pass are the user and pass this bot will try to oper up with when it connects, before joining channels.

Additional configuration can (and should) be done in the following files:

  • pisgPrefix.cfg - Optional. When pisg.cfg is regenerated by the bot (for example, when a user invites the bot to a new channel), this prefix is prepended to that file. You can use this to do a lot, pisg is very customizable. For example, you could ignore specific nicks or ignore certain words.
  • channels.txt - List of channels bot is currently in and which it will join on startup. Plain text, separated by newlines. Do not edit while bot is running.
  • indexTemplate.html - Optional. If you don't have this, you won't have an autogenerated HTML channel listing in index.html in locations.stats. This is the HTML template that the bot will use to generate an index of all sites using this bot. Place whatever content you want in here. When it is loaded by the bot, the string "%lis%" will be replaced by a series of HTML <li> elements with <a> links to the stats pages for each channel. You can check out the example used for Snoonet at snoonet-chanstats-template

pisg Configuration

pisg does the heavy lifting of collating log files and generating the statistics HTML files. Once StatsBot has been invited to it's first channel, it will generate a pisg.cfg file in this directory. That file consists of the contents of pisgPrefix.cfg prepended to a bunch of channel configuration blocks based off the locations specified in settings.json. You should create a cron job to run pisg using the pisg.cfg generated by the bot. This cron job will cause the statistics HTML files to be generated in locations -> stats on a regular interval.

The pisg docs are extensive and have many useful examples on how to do things including customizing the display of the stats, ignoring specific users or words, and adding or removing certain types of stats.

Starting the bot

ruby bot.rb to start the bot.

Bot usage and commands



📈 Chat bot which logs conversations on IRC for analysis by pisg.







No releases published


No packages published