Home
kameloso is an IRC bot with Twitch support. It's text-based and runs in a terminal or console.
Broadly speaking, it connects to a server and idles in your channels, listening to commands. A command is a word preceded by a prefix. The default prefix is !, and an example command would as such be !word.
Features are split into plugins. Not all plugins offer commands, but they are the main way you interact with most plugins. For the list of plugins and how to use them, see Current plugins. Plugins are enabled and disabled in the configuration file.
You can run a copy of it on your own machine! You only need very minor terminal/console know-how for this; in essence, only how to navigate directories and how to pass arguments to programs. The readme contains a guide with step-by-step instructions on how to get started. There are pre-compiled binaries available for Windows and Linux under Releases, so you don't even need to build it yourself. It works on other architectures too, like macOS and the Raspberry Pi, but for those you do need to build it yourself.
| Section |
|---|
| 1. User classes |
| 2. User identification |
| 3. Channels |
| 4. Program |
| 5. Twitch |
| 6. Problems? |
Commands are often restricted so that not everyone can use them. The bot ranks users into user classes, and commands are declared as needing a permissions level of this or that class (or higher). On a normal IRC server users have to be assigned classes manually, whereas on Twitch they can additionally be inferred so that all moderators get a specific class, all VIPs another, all subscribers a third, etc. Classes are per-channel, so one bot instance can serve any* arbitrary number of channels in parallel. There is an administrator class that you can assign yourself to, which spans across all channels.
The available classes are:
| Class | Description |
|---|---|
admin |
Global program administrator with the highest privileges. |
staff |
Channel staff or owner. On Twitch, this is the streamer. |
operator |
Channel operator. On Twitch, these are moderators. |
elevated |
Trusted people with elevated permissions. On Twitch, these are VIPs. |
whitelist |
Normal, explicitly trusted users. |
registered |
People logged onto the server's services. On Twitch, these are subscribers. |
anyone |
Normal, unknown users. |
blacklist |
Known bad users. |
A class of admin can only be assigned in the configuration file. registered and anyone can only be inferred and not manually assigned. Nothing is ever inferred to whitelist. Additionally, an IRC channel "op" is not automatically inferred to be operator and requires manual assignment. Manual assignment can be done using the Admin plugin or by modifying the users.json file.
Users are identified by what services account they are logged in as. Services are a common way for IRC servers to manage permissions and privileges. Common examples would be NickServ and AuthServ. Not all servers support services though, and on those servers may be identified by the traditional hostmasks by changing a setting in the configuration file. On Twitch, users are simply identified by their account name.
A user that cannot be uniquely identified is assigned the class anyone.
Channels can either be home channels or guest channels. A home channel is one in which the bot listens to commands. A guest channel is one in which the bot simply idles, but may still do things like log channel conversations. Both types of channels are declared in the configuration file or at the command line.
The program itself is text-based and runs in a console or a terminal. It works in Windows, on Linux and on macOS. Since any number of channels may be served in parallel, if you're interested in trying the bot but don't want to run it yourself, contact me and I'll host an instance on a headless server.
See the quickstart guide for Windows and the quickstart guide for Linux for some copy/paste-friendly instructions.
Twitch chat is based on IRC, and with some few exceptions the whole bot will work on it. In addition, it serves some Twitch-specific commands and features. You have to perform a few initial steps to connect to the Twitch chat server. A guide has been written that you can initiate by passing --setup-twitch to the program. On Windows you additionally need to download a library (OpenSSL) to make secure connections possible.
If the bot is not a moderator of your channel, the server very aggressively rate-limits its messages. To avoid this, just make sure to make it a moderator via the Twitch chat interface.
See the wiki section on Twitch for more details.
If you run into any problems whatsoever, feel free to start a discussion or file an issue.