Idea: hooks

  • Impact: irccd
  • Status: implemented
  • Target version: 3.1.0


Irccd is extensible using both C++ and Javascript APIs. When someone usually searches for a bot, it looks at its aspects, features and optionally the scripting language. Irccd is one of the first bot written in C++ and using Javascript as optional scripting language. Irccd also have interesting features such as rules, templates, transports and multiple servers. That said, people may like irccd but dislike its Javascript APIs for some reasons. This proposal aims to fix that in a clean and simple way.


The key idea is to offer to irccd a way to call external scripts upon receptions of IRC messages. Thus one can use any language to write its own set of actions.

Comparison to plugins

While both hooks and plugins provide a way to extend irccd, they have different aspects.

  • Plugins are permanently loaded while hooks are evaluated only when required. On the other hand, starting hooks on demand takes slightly more time than calling plugins.
  • Hooks are much less powerful than plugins, you need to call irccdctl to respond to events.
  • Hooks let you write your script in any language while plugins are only available in Javascript and C++.
  • Hooks can not use the irccd templates nor rules systems.


Hooks are simply defined in the irccd.conf file under a new section hooks. Then user adds any key-value pair as necessary for every hook. The key is used as hook identifier.


database = "/bin/" 

Available functions

The IRC events are passed as arguments in the form event arguments....

  • onCommand server origin channel message
  • onConnect server
  • onDisconnect server
  • onInvite server origin channel
  • onJoin server origin channel
  • onKick server origin channel target reason
  • onMe server origin channel message
  • onMessage server origin channel message
  • onNick server origin nickname
  • onPart server origin channel reason
  • onTopic server origin channel topic

Note: for the moment onNames and onWhois are deferred.

Transport commands

The following commands are available.


List all hooks and their status, for security purposes the path is not shown.

$ irccdctl hook-list
database enabled
destroyer disabled

hook-enable and hook-disable

Basically self explanatory

$ irccdctl hook-enable destroyer
$ irccdctl hook-disable database

Updated by David Demelier over 3 years ago ยท 10 revisions