cat to IRC
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
dispatcher Switch to forked go-ircevent and enable IRC3 caps Jan 25, 2017
examples add SASL login support Feb 21, 2019
tcplistener Switch to forked go-ircevent and enable IRC3 caps Jan 25, 2017
util Improve message formatting Nov 14, 2018
webhook_test_data/github Webhook test script Feb 21, 2019
.gitignore Gitignore binary and config Feb 21, 2019
.travis.yml Use xenial build env Feb 21, 2019
Dockerfile Add dockerfile. Jan 28, 2019
LICENSE License and readme Jan 12, 2017
command.go minor: Only execute command when commands.handler is defined Oct 31, 2017
irc.go Add -debug command line flag Feb 21, 2019
main.go Add -debug command line flag Feb 21, 2019


Build Status

A reimplementation of irccat, the original ChatOps tool, in Go.

irccat lets you easily send events to IRC channels from scripts and other applications.


Download the latest release from Github, put the example config in /etc/irccat.json or the local directory and customise it, and run!


Just cat a string to the TCP port - it'll be sent to the first channel defined in your channel list:

echo "Hello world" | nc irccat-host 12345

Or specify a channel or nickname to send to:

echo "#channel Hello world" | nc irccat-host 12345
echo "@nick Hello world" | nc irccat-host 12345

You can also send to multiple recipients at once:

echo "#channel,@nick Hello world | nc irccat-host 12345

And set a channel topic:

echo "%TOPIC #channel Channel topic" | nc irccat-host 12345

IRC formatting is supported (see a full list of codes):

echo "Status is%GREEN OK %NORMAL" | nc irccat-host 12345


HTTP listeners are configured by setting keys under http.listeners.

Generic HTTP Endpoint

"generic": true

An endpoint for sending messages similar to the TCP port. You can use curl in lieu of netcat, with -d @- to read POST data from stdin, like so:

echo "Hello world" | curl -d @- http://irccat-host/send

Everything that works via netcat also works by POST to /send. Note that this endpoint is unauthenticated.

Grafana Webhook

"grafana": "#channel"

Grafana alerts can be sent to /grafana. They will be sent to the channel defined in http.listeners.grafana. Note that this endpoint is currently unauthenticated.

GitHub Webhook

"github": {
	"secret": "my_secret",
	"default_channel": "#channel",
	"repositories": {
	    "irccat": "#irccat-dev"

Receives GitHub webhooks at /github. Currently supports issues, issue comments, pull requests, pushes, and releases. The webhook needs to be configured to post data as JSON, not as form-encoded.

The destination channel for notifications from each repository is set in http.listeners.github.repositories.repo_name, where repo_name is the name of the repository, lowercased.

If http.listeners.github.default_channel is set, received notifications will be sent to this channel unless overridden in http.listeners.github.repositories. Otherwise, unrecognised repositories will be ignored.

GitHub can be configured to deliver webhooks to irccat on an organisation level which, combined with the default_channel setting, significantly reduces configuration effort compared to GitHub's old integrations system.

IRC → Shell

You can use irccat to execute commands from IRC:

?commandname string of arguments

This will call your commands.handler script, with the following environment variables:

  • IRCCAT_COMMAND: The name of the command, without the preceding ? ("commandname" in this example)
  • IRCCAT_ARGS: The arguments provided ("string of arguments" in this example)
  • IRCCAT_NICK: Nickname of the calling user
  • IRCCAT_USER: Username of the calling user
  • IRCCAT_HOST: Hostname of the calling user
  • IRCCAT_CHANNEL: Channel the command was issued in (may be blank if issued in PM)
  • IRCCAT_RESPOND_TO: The nick or channel that the STDOUT of the command will be sent to
  • IRCCAT_RAW: The raw IRC line received

The command handler's STDOUT will be sent back to the nick or channel where the command was issued.

An example python command handler, which dispatches commands to individual shell scripts, can be found in examples/

irccat will only recognise commands from users in private message if the user is joined to commands.auth_channel defined in the config.

Full list of differences from RJ/irccat

  • Supports TLS connections to IRC servers.
  • HTTP endpoint handlers.
  • Doesn't support !join, !part commands, but does automatically reload the config and join new channels.
  • Arguments are passed as environment variables to the command handler script, rather than as a single argument.