node package manager


Streaming bot makers library with regex handlers


npm status build status dependency status coverage status

Gu is a streaming bot makers library that you can pipe your transports to and from.

It has two main features:

  • regular expression handlers in a style similar to hubot (but without all those annoying environment variables and coffee-script..)
  • streaming input and output allows for easy control, extensibility and transport-less testing of handlers


Find a library that does the transport you want, say irc-stream:

Create a main file; bot.js:

var gu = require('gu')(scriptPath, files);
var ircStream = require('ircStream')(name, server, {chan: [chan]});

The script path and the files (relative to the scriptpath) will be watched for changes, and is assumed to contain handlers exported behind a function.

Then, put a file in your scriptpath, love.js, say, and add handlers therein:

module.exports = function (gu) {
  gu.handle(/^what is (\w*)$/, function (say, match) {
    if (match === 'love') {
      say("baby don't hurt me");

Then fire up the bot with node bot.js, navigate to the specified server and channel (in ircOpts), and try saying botName: what is love in the channel.

Changing the handler in love.js will result in different behaviour without having to restart bot.js.

A more extensive example is avaiable in the example directory.

Complete examples

The following bots are built on gu:

Stream Specification

A gu instance expects to have objects written to it, and will new objects readable on the other end.

Therefore, the sensible interface (unless you are doing some weird asymmetrical connection setup), is a Duplex stream in objectMode.

Inputs & Outputs

Expected input objects:

  user: String, // unique identifier of user 
  channel: String, // unique group chat identifier (if relevant) 
  message: String, // raw message to be matched by gu 

Output objects are identical. As an example an example message from/to irc-stream can look like this { user: 'clux', channel: '#quake', message: 'hi' } for a private message, the channel key is unset.

An optional name property may be set for the convenience of the stream handler (such as xmpp-stream). It is used when doing group chat highlighting without having to necessarily use the larg UID. For IRC it is unused.

Compatible Transports

Best tested: irc-stream.

Early prototype of xmpp-stream also available.


A few options can be passed along to the gu instance as the third parameter, these are:

  verbose: Boolean // enable regex match log when gu receives messages 


Emitted logs are available on the instance as gu.log. They are emitted in the form of smell.

To actually print them out, you should use sulfur as such:

var sulfur = require('sulfur');
sulfur.absorb(gu.log, 'gu');

You can also log from gu handlers by calling the log methods error, warn, or info on gu.log:

gu.handle(/^(.*)$/, function (say, match) {"matched the everything handler with", match);


$ npm install gu


MIT-Licensed. See LICENSE file for details.