Limnoria: a Python IRC bot with an ACL system and 400 commands

Successor to Supybot that keeps the old configurations working

Limnoria is a multipurpose Python IRC bot, described in the README as designed for flexibility and dependability while staying easy to install, set up and maintain. The project states that it aims to be an adequate replacement for most existing IRC bots.

The lineage matters more than usual here. Limnoria has been the successor of Supybot since 2010, and the README is explicit that it provides many new features but keeps full compatibility with existing configurations and plugins. For anyone who inherited a Supybot setup, or who has an old plugin collection, that compatibility is the reason to look at Limnoria rather than at a bot written from scratch.

The scale of the built-in functionality is the second headline. The README counts more than 60 builtin plugins providing around 400 actual commands, and separately there are dozens of third-party plugins written by dozens of independent developers, listed in a plugin index.

That combination defines the audience. This is not a minimal bot you extend, it is a complete bot with a plugin ecosystem, a user-facing command set and an administration model, and the interesting question for an adopter is how much of that you want to inherit.

The documentation lives at docs.limnoria.net, the default branch is master, the last push was on 2026-10-18, and the repository is not archived. The project has no GitHub releases, so version tracking is done through the package and the changelog rather than through tags on the platform.

Capabilities, not channels, decide who may run a command

The ACL system is the part of Limnoria that distinguishes it from a bot with a hardcoded admin list, and it is worth understanding before anything else.

The README points to an ACL system it describes as very flexible for controlling access to commands. The model is capability based: a user holds capabilities, and a command requires a certain capability to run. The channel and the command are matched against the configuration rather than against hardcoded checks in the plugin code.

The practical consequence is that access control is data, not code. A new command in a new plugin inherits whatever capability rules the configuration already contains, and an administrator can grant or revoke the ability to use a command for a specific person without touching a plugin. That is a meaningfully different maintenance model from a bot where each plugin decides for itself who is allowed.

It also means the bot's security depends on the configuration, and a misconfigured capability grants access to something you did not intend. A capability system gives fine control, and fine control is where the mistakes live. Anyone deploying this should read the capabilities documentation page in the README's link list before connecting the bot to a channel with people in it.

The second subsystem is the configuration system, described in the README as equally capable and used to customise the bot. It is the counterpart to the ACL system: one decides who may do what, the other decides how the bot behaves.

Configuration you change from inside the chat

The configuration system is what makes a Limnoria bot manageable in practice, and its most distinctive property is that it is editable from IRC itself.

A bot that runs unattended on a server is awkward to administer if changing a setting means an ssh session, a text editor and a restart. Limnoria is built so that a user with the right capability can set a configuration value, and the change takes effect without the bot going away. The README calls it a very flexible configuration system to customise your bot, and the dedicated documentation page is linked from the README for exactly this.

The plugin model makes this work. The README says it is very easy to write your own plugin with only basic knowledge of Python, and the documentation includes a plugin tutorial. A plugin declares its commands, its default configuration values and the capabilities its commands need, and the framework handles the rest. That is how you get dozens of independent developers contributing plugins that behave consistently with the built-in ones.

The repository layout supports this division of work. The plugins directory holds the plugin collection, the src directory the framework, the locales directory the translations, the man directory the manual pages, and the test directory the test suite. The presence of a locales directory, and of a French channel on Libera.Chat as the only non-English support channel listed, says something concrete about the internationalisation work involved.

The one thing to keep in mind is that editing configuration from a chat is a convenience with a security dimension. Anyone who can reach the bot with the right capability can change it, which means the capability configuration and the network the bot listens on are the two things that determine how exposed the bot is.

Installing: pip, then the wizard

The README points first-time users to an install guide and then gives a short version. The sequence installs the interpreter tooling, installs the package for the current user, and finally runs a setup wizard:

sudo apt-get install python3 python3-pip python3-wheel
pip3 install --user limnoria
# You might need to add $HOME/.local/bin to your PATH
supybot-wizard

Two details in those lines are worth noticing. The install is a user install, not a system one, which is why the note about adding $HOME/.local/bin to your PATH is there. And the wizard keeps the Supybot name, because the command names and the config format are kept compatible with the predecessor.

The wizard exists because the alternative is hand-writing a configuration file before you understand the format. Running it is the right first step; editing the generated configuration by hand afterwards is fine once you know what the keys do.

For distribution packages and source builds, the Makefile at the repository root provides the targets. The build recipe runs setup.py sdist, the install recipe runs setup.py install with a DESTDIR, and there are separate targets for generating an rpm and for building a Debian package for Python 3. The test recipe runs the test harness with the plugins directory pointed at the repository's own plugins folder, which is how the built-in plugins are exercised.

The package metadata is modern enough, with setuptools and wheel as the build requirements, while the setup.py file still carries the classic three-clause BSD licence header with the copyright lines of the original Supybot authors, Jeremiah Fincher, James McCoy, Valentin Lorentz and Ian Wienand.

Optional dependencies decide what the bot can actually do

The requirements file is organised in three tiers, and the distinction tells you what you are getting at install time.

Only setuptools is mandatory. Everything else is optional, and the file is unusually honest about why. chardet is there to detect the encoding of incoming IRC lines when they are not UTF-8, and the file carries a sharp comment about the upstream 7.0.0 release being rewritten in two weeks and the project pinning below it. python-gnupg enables authentication based on GPG tokens. PySocks provides a SOCKS proxy, which the file says is typically used to connect to IRC via Tor. pyxmpp2-scram covers the scram-sha-256 SASL mechanism.

Then a third tier for plugin dependencies: cryptography is required to load the Fediverse plugin, specifically to implement HTTP signatures so Mastodon instances can be reached with AUTHORIZED_FETCH enabled. feedparser is required for the RSS plugin. python-dateutil enables fancy time string parsing in the Time plugin, ddate provides the ddate command, and tzdata is needed on Windows for the Geography plugin's IANA timezones.

This design is a real strength. A bot that needs a GPG stack, a SOCKS proxy and a cryptography library installed before it will start is a bot most people will not install. Making each of those an optional extra means a plain install works, and the features that need heavy dependencies announce themselves when you enable the plugin.

It also means the failure mode is a missing feature rather than a missing bot, which is the right way round. A user who enables the Fediverse plugin without cryptography gets an error at that point, not a broken install.

Where Limnoria is the wrong tool

The first wrong-tool case is not really about Limnoria at all, it is about IRC as a protocol. The repository topics list gpg, i18n, irc, ircv3, rss, sasl, tls and supybot, which is a good summary of a bot that has grown with the protocol. A team whose users are on a modern chat platform, on a forum, or on a messaging API has no use for any of it, and no amount of plugin count changes that.

The second is operational maturity. This is a volunteer project. The support channel on Libera.Chat and the issue tracker are where you ask questions, and the README invites people to post on the issue tracker if they think there is a better way to do something. The absence of GitHub releases is consistent with that: there is no published compatibility matrix and no tagged support window. If you are putting a bot in front of an organisation, that is a procurement conversation, not a technical one.

The third is the licence. The repository lists a custom licence that GitHub cannot classify, and the setup.py header shows a three-clause BSD text, while the licence file at the root is named LICENSE.md. Those are consistent with each other in practice, but a custom licence that a hosting platform cannot classify is worth reading directly rather than inferring from a badge.

The fourth case is a bot with a single purpose. If you need one command that announces a deployment to a channel, wiring up 60 plugins, an ACL system and a configuration editor is more work than writing the announcement script. Limnoria is the right answer when you want the whole framework, and overkill when you want one function.

How to write a plugin, and where the extension surface really is

The plugin tutorial linked from the README is the entry point for anyone extending the bot, and the claim is that basic knowledge of Python is enough. That is plausible given how the framework is arranged, because a plugin is a Python class that declares a set of commands, and the framework handles dispatch, capability checks, configuration defaults and help output.

The repository reinforces this by keeping plugins in their own top-level directory, separate from the src directory that holds the framework. The test target points at that plugins directory explicitly, so a plugin can be exercised in isolation.

Third-party plugins are the interesting part. The README says there are dozens of them written by dozens of independent developers, and they are listed alongside the built-in ones in the same plugin index. From the user's point of view there is no distinction between a built-in command and a third-party one, which is what makes the plugin ecosystem work without a central curation bottleneck.

The cost of that model is that the ACL and configuration systems are the contract. A third-party plugin that declares its commands correctly inherits the capability system, and one that does not will quietly expose them. So for anyone running a public bot, the plugin list is a security surface, and the capability documentation is the thing to read before installing anything from outside the project.

The framework has also absorbed a lot of protocol evolution. The topics list includes ircv3, sasl and tls, and the requirements file names specific SASL mechanisms, which tells you the IRC protocol side is not frozen at the RFC level. That is the practical reason a bot written for plain IRC in 2005 is not a substitute here.

Editorial conclusion

Limnoria fits an operator who wants a long-running IRC bot whose configuration and access rules can be changed without a restart, and a Python developer who wants to add behaviour as a plugin rather than by patching the bot. It is the wrong choice for a team that needs a supported commercial platform, for a deployment where the licence terms are unclear to you, or for anything outside IRC. Before adopting it, read the LICENSE.md file in the repository, run supybot-wizard rather than hand-editing the config, and confirm the optional dependencies your plugins need are installed, since the core package deliberately ships without them.

Frequently asked questions

Official sources

1. Issues
2. progval/Limnoria on GitHub
3. Project website
4. README