gophirc, an event based, multi server IRC framework written from scratch, in Go
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.

GoDoc Go Report Card Build Status gophirc version Twitter URL


A simple IRC bot framework written from scratch, in Go.


Event based IRC framework.


The API might break anytime.

Framework managed events

  • Manages server PING requests (not CTCP PING)
  • Registers on first NOTICE *
  • Identifies on RPL_WELCOME (event 001)
  • Joins the received invites & sends a greeting to the channel
  • Logs if the bot gets kicked from a channel


  • Capability to connect to multiple servers
  • Multiple per event callbacks
  • State & general logging
  • Graceful exit handled either by a SIGINT (Ctrl-C)
  • Parses a user from an IRC formatted nick!user@host to a User{}
  • Config implements a basic checking on values
  • Already implemented basic commands - JOIN, PART, PRIVMSG, NOTICE, KICK, INVITE, MODE, CTCP commands
  • Many (?) more

Events & callbacks

An event follows the next schema:

type Event struct {
    Raw       string   // the whole raw line
    Code      string   // the reply code
    Source    string   // the source of the event (server, user)
    Arguments []string // the arguments after the event code

    User    *User  // if we can parse a user from the source, add the parsed user here
    Message string // if it's a PRIVMSG, add the message here
    ReplyTo string // if it's a PRIVMSG, add the recipient here (user or channel)

You can set callbacks for, technically, all events - numeric reply codes (e.g. "001", "900", etc.) or alpha codes (e.g. "NOTICE", "INVITE", etc.).

Note: CTCP events will have the code set to the corresponding CTCP action, not PRIVMSG.

The framework already binds callbacks for:

  • 001 - to identify with NickServ
  • 900 - to join the channels specified in config
  • NOTICE - only the first event, in order to register with the network
  • INVITE - joins the channel & greets


Setting up a simple config:

  "servers": {
    "first": {
      "address": "irc.server.tld",
      "port": 6667,
      "nickname": "gophirc",
      "nickserv_password": "my_nick_pass",
      "channels": [
      "admins": [

Note: a full config example can be found in the config/config.json.example file.

Setting a simple bot:

package main

import (

func main() {
    var wg sync.WaitGroup
    conf, _ := config.Parse("config.json")
    irc := gophirc.New(conf.Servers["name"], &wg)

Note: error handling remains an exercise for the reader

Setting up a callback to respond to a CTCP VERSION:

irc.AddEventCallback("VERSION", func(e *gophirc.Event) {
    irc.Notice(e.User.Nick, "\001My own Go bot!\001")

Setting up a callback to check for custom messages:

irc.AddEventCallback("PRIVMSG", func(e *gophirc.Event) {
    replyTo := e.Arguments[0]
    message := strings.Join(e.Arguments[1:], " ")[1:]

    switch message {
    case "shrug":
        irc.PrivMsg(replyTo, `¯\_(ツ)_/¯`)

For more examples on usage, please see gophircbot.

To do

  • Add tests
    • Config
    • User
    • Logger
    • Helpers
    • IRC
    • commands
  • Add defaults
    • Nickname, Username, Realname
  • Parse CTCP messages into events
  • Add more commands: MODE, KICK, etc.
  • Add regex matching for nicknames, channels
  • Connect Multiple servers
  • Add ignored users