Nebulous Program Mechanic
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »



    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.



    npm i gu

    Downloadsweekly downloads








    last publish


    • avatar