Simple, extensible chatbot platform, supports Slack (with more to come).
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

snarl snarl

NPM version Build Status

Simple chat bot (currently for Slack), extensible with plugins.

Despite his name, snarl is just a fuzzy and friendly goofball. He's been with us for several years, since the beginning of the Coding Soundtrack community. He's an awesome automaton that helps us with a great many things, so be nice to him.

Avatar for snarl is by @yiyinglu, who designed the original avatars for

If you'd like to test him out, join us on the Maki Slack, where snarl helps us develop the Maki Framework.

Quick Start

You'll need to create a Bot User for your Slack organization, generally found at Once the integration is added, you'll be given an API token: place this token into config/index.json. For more help, Slack has great documentation on bot users.

  1. Install via npm install snarl -g, or simply clone1 this repository and run npm install as usual.
  2. Modify config/index.json to contain your Slack token (see paragraph above).
  3. Execute npm start in the source directory, or snarl if you installed globally.

That's it. You'll see snarl come online! If you install snarl globally via npm install snarl -g, you can also simply type snarl at any time (for example, inside of a screen or a tmux session) to run the bot.

1: if you want to make modifications, you should fork it first!

Naming Your Bot

If you want to give snarl a different name, you can configure it via Slack (see link above), or add a name property to config/index.json.


snarl supports plugins. We've kept the default list short but fun. We'd love to see even more contributions!

Plugins for snarl can add commands or other functionality. For example, the included karma plugin lets snarl keep track of karma for various users.

Using Plugins

Plugins can be autoloaded from either a single file in ./plugins/plugin-name.js or an NPM module named snarl-plugin-name. To autoload a plugin, add the plugin name to the plugins array in config/index.json:

  "name": "snarl",
  "plugins": ["erm", "karma"],
  "store": "data/store",
  "slack": {
    "token": "some-token-xxxooooo",

...and simply call autoload():

var Snarl = require('snarl');
var snarl = new Snarl();

// autoload plugins found in `config/index.json`

// start snarl, as normal

To use another plugin, simply require it, as follows:

var Snarl = require('snarl');
var snarl = new Snarl();

// import the karma plugin
var karma = require('./plugins/karma');

// use the karma plugin we required above

// start snarl, as normal

Included Plugins

The list of available plugins (via ./plugins/plugin-name) is as follows:

  • karma, which keeps track of user karma, as incremented by @username++.
  • facts, which provides !TopologyFacts (mathematical topology facts), !SmiffFacts (facts about Will Smith), and !InterstellaFacts (facts about Interstella 5555)
  • meetups, which responds with a simple message telling your community about in-person meetups.
  • erm, which transforms the text of a user message into ERMEGERD speech using martindale/erm.
  • beer-lookup, which provides !brew <beerName> to look up and describe a beer via BreweryDB.

Other Plugins

  • snarl-eliza is a simple AI using the ELIZA self-help chatbot created by Joseph Weizenbaum between 1964 and 1966.
  • snarl-wine-lookup is a simple plugin for performing wine-lookups via the snooth wine api, using the !vino command and several optional parameters. Cheers!

Writing Plugins

To write a snarl plugin, create a new NPM module that exports a map of triggers your bot will respond to. You can use either a simple message string, or a function that expects a callback:

module.exports = {
  'test': 'Hello, world'

For more complex functionality, use the callback feature:

module.exports = {
  'test': function(msg, done) {
    // simulate an asynchronous task...
    setTimeout(function() {
      // error is first parameter, response is second
      done(null, 'Your message was: ' + msg.text + '\nYour triggers were:' + msg.triggers);
    }, 1000);

We ask that you publish your plugins via npm, name them snarl-yourplugin, and add both the snarl and slack keywords to your package.json.

Thanks! We hope you enjoy.