llimllib/limbo

A simple, clean, easy to modify Slack chatbot - Made by Bill Mill who is an ex-adhoc member, but still has his rss feed that posts to an adhoc channel every day... pretty awesome.

Summary

limbo is a Python-based Slack chatbot released under the MIT license and designed to be simple, clean, and easy to modify. The maintainer considers it feature complete and has placed the project in maintenance mode, accepting contributions while occasionally updating dependencies. Engineers extend the bot by adding small Python files rather than configuring a framework.

What it is useful for

limbo is useful for teams that want a self-hosted Slack bot they can read end-to-end and customize without depending on a third-party service. It ships with a default plugin set covering common chatroom needs: emoji lookup, coin flip, GIF and image search, Google search, location map, polls, weather, and Wikipedia lookups. Because each command is a plain Python file in a plugins directory, the project also works well as a starting point for engineers who want to learn Slack integration patterns or wire a small internal tool into a Slack channel.

How engineers can use it

The README documents a short setup flow: clone the repo, create a Slack bot user, then export SLACK_TOKEN with the API token and run make run (or make repl for a local REPL). The maintainer recommends running inside a virtualenv and warns that running as sudo clears the environment, which can prevent the bot from finding SLACK_TOKEN. The officially supported Python is 3.10 or newer; older versions may still run but are not tested because of an unresolved urllib3 inconsistency in the test fixtures.

Configuration is via flags and environment variables. Useful flags include --test/-t for the REPL, --hook to pick the hook to exercise (default message), -c to run a single command, -d to set the sqlite3 database path, and --pluginpath/-pp to point at a different plugins directory. Environment variables cover the required Slack token, log level, log file, log format, and the comma-delimited LIMBO_PLUGINS list.

Adding a command is a matter of dropping a Python file into the plugins directory with an on_message function that returns a string. Plugins ignore other bots by default; defining an on_bot_message handler opts in to that traffic. The !help command lists available plugins, and !help <plugin> shows help for one. Full per-plugin documentation is hosted on the project's wiki, which the README points to for each default plugin.