About HexBot
At its peak in the early 2000s, Internet Relay Chat had millions of daily users spread across networks like EFnet, Undernet, DALnet, and Quakenet — a federated mesh of servers that nobody owned, running a protocol that anyone could implement. Hackers, open-source developers, gamers, and underground communities all operated in real time, in plain text, across thousands of channels. It was the internet's town square, engine room, and back alley all at once.
Bots were an inevitability. Channels needed protection — flood attacks and takeover attempts were a daily reality on the early net, and human operators couldn't stay awake forever. So people automated them. A bot could hold ops, enforce channel modes, kick spammers, and reconnect after a netsplit without anyone lifting a finger. From there the use cases multiplied: DCC file servers seeding warez and MP3s to anyone who asked, trivia bots keeping quiet channels alive, seen bots tracking who was last online, dice rollers, quote databases, weather fetchers pulling data from early web APIs. Each bot was a tiny daemon with a specific job, running 24/7 on whatever hardware its author could afford to leave powered on.
The architecture that emerged from that era was surprisingly elegant. An event table. A permission system built on flags. A way to attach handlers to patterns at runtime and detach them without restarting. These ideas proved so sound that every serious IRC bot written since has reinvented some version of them. HexBot is our version — a modular IRC bot for Node.js, written in TypeScript, that takes those same principles and applies them with the tools available today. Hot-reloadable plugins. Type-safe APIs. Docker-ready deployment. The spirit of those 3am channel guardians, running on infrastructure that Oikarinen could never have imagined.
Key Features
- Modular plugins — load, unload, and hot-reload without restarting
- Flag-based permissions — owner, master, op, voice, per-channel and global
- Bind system — 16 event types, pattern-matched triggers
- SASL authentication — PLAIN and EXTERNAL (CertFP) support
- IRCv3 caps — extended-join, account-notify, chghost
- SOCKS5 proxy — route through Tor or SSH tunnels
- DCC CHAT party line — remote admin sessions without IRC access
- NickServ integration — Atheme and Anope, optional ACC verification
- IRC CASEMAPPING — rfc1459, strict-rfc1459, ascii
- SQLite persistence — namespaced per-plugin key/value store
Architecture
HexBot uses a two-tier module system. Core modules are always loaded and provide the bot's foundational services — the IRC bridge, dispatcher, permission engine, channel state, and database. Plugins are isolated, hot-reloadable units that register event binds against the dispatcher and never depend on each other.
The bind system is the heart of the bot. Plugins call bind(type, flags, mask, handler) to subscribe to IRC events. The dispatcher matches incoming events against all registered binds, checks permissions, and calls handlers in registration order.
Permission Flags
| Flag | Level |
|---|---|
| n | Owner — full access, implies all others |
| m | Master — user management |
| o | Op — channel commands, bot admin |
| v | Voice — reserved for plugin use |
| - | Anyone — no restriction |
Tech Stack
- Node.js 24+ — ESM modules, modern runtime
- TypeScript 5 — strict mode, full type coverage
- irc-framework — IRC protocol transport and parsing
- better-sqlite3 — synchronous SQLite, namespaced per plugin
- Vitest — unit tests with v8 coverage
- GPL-2.0 — open source license