GehenBot

GehenBot is an IRC bot written in Go. It connects to IRC networks and responds to events by executing external scripts (Python, shell, etc.).

Building

go build -o gehenbot .

Requires Go 1.25+.

Usage

./gehenbot config.yml

Accepts YAML (.yml/.yaml) or JSON (.json/.jsn) config files.

Configuration

See gehenbot.yml for an example configuration.

Global Options

Field	Description
verbose	Enable verbose logging
debug	Enable debug logging
log_dir	Directory for log output
script_dir	Directory containing trigger scripts
http_port	Port for the webhook HTTP server (0 to disable)
https_cert	TLS cert for HTTPS webhook server
https_key	TLS key for HTTPS webhook server

Networks

The networks array defines one or more IRC connections:

Field	Description
name	Bot instance name (for logging)
nick	IRC nickname
owner	Owner's nick (for bot admin commands)
user	IRC username (IDENT)
server	IRC server hostname
port	IRC server port
ssl	Use TLS connection
ssl_verify	Verify TLS certificate
channels	List of channels to join on connect
authorized	List of glob patterns for authorized users
webhooks	Map of channel name to script (e.g. "#chan": "script.py")
triggers	Map of IRC events to trigger configs (see below)

Triggers

Triggers map IRC events to external scripts. Each entry specifies the event type and the script to execute.

triggers:
  PRIVMSG:
    - pattern: "^\\.weather.*$"
      command: "weather.py"
  JOIN:
    - command: "greet.sh"
  PART:
    - command: "comeback.py"

For PRIVMSG triggers, a pattern (regex) is required to match messages. For JOIN/PART triggers, only command is needed.

External Scripts

Scripts are standalone executables in the configured script_dir. When a trigger fires, the script is spawned with four arguments:

<script> <nick> <target> <message> <botnick>

Arg	Description
nick	User who triggered the event
target	Channel or user the event was directed at
message	The message content (for PRIVMSG)
botnick	The bot's current nickname

The !BOT Protocol

Scripts communicate back to the bot by writing lines to stdout. Lines starting with !BOT are interpreted as bot commands. All other lines are sent as PRIVMSG to the triggering channel.

Command	Args	Description
!BOT JOIN	<channel>	Join a channel
!BOT PART	<channel>	Leave a channel
!BOT SAY	<target> <message...>	Send a PRIVMSG
!BOT NICK	<newnick>	Change nickname
!BOT QUIT		Disconnect
!BOT OP	<channel> <nick>	Give operator status
!BOT DEOP	<channel> <nick>	Remove operator status
!BOT VOICE	<channel> <nick>	Give voice
!BOT DEVOICE	<channel> <nick>	Remove voice
!BOT KICK	<channel> <nick> [reason]	Kick a user
!BOT BAN	<channel> <mask>	Ban a user mask

Example script:

#!/usr/bin/env python3
import sys

nick, target, msg, botnick = sys.argv[1:5]

if "hello" in msg.lower():
    print(f"Hello, {nick}!")

Authorization

If an owner is configured, only that user can use .authorize in IRC to add authorized user glob patterns. Users not matching the owner or an authorized pattern are ignored.

.authorize *!*@*.example.com

Webhook Server

When http_port is set, GehenBot starts an HTTP server for webhooks (e.g., from Forgejo/Gitea). Routes are defined per-channel in the config's webhooks map.

POST /<botnick>/<channel>

The configured script receives:

• The channel as argv[1]
• Request body on stdin
• HTTP headers as WEBHOOK_HDR_* environment variables
• WEBHOOK_METHOD and WEBHOOK_URI environment variables

Each line of script stdout is sent as a PRIVMSG to the channel.

Scripts

See scripts/ for included scripts:

• greet.sh - Greets users on JOIN
• comeback.py - Begs departing users to stay
• weather.py - OpenWeatherMap lookup (.weather)
• linkgrabber.py - URL tracking and search (.link)
• join.py, part.py - Channel management
• op.py, deop.py, voice.py, devoice.py - Channel mode commands
• kick.py, ban.py - Moderation commands
• forgejo.py - Forgejo/Gitea webhook formatting