kameloso idles in your channels and listens to commands and events, like bots generally do.
Current functionality includes:
- bedazzling coloured terminal output like it's the 90s
- automatic mode sets (e.g. auto
+oon join for op)
- fetching and echoing titles of pasted URLs
- sed-replacement of messages (
- saving notes to offline users that get played back when they come online
- channel polls
- works on Twitch, including optional streamer plugin
- SSL support
- more random stuff and gimmicks
All of the above are plugins and can be runtime-disabled or compiled out. It is modular and easily extensible. A skeletal Hello World plugin is 20 lines of code.
Please report bugs. Unreported bugs can only be fixed by accident.
-n --nickname Nickname -s --server Server address [irc.freenode.net] -P --port Server port  -A --account Services account name -p --password Services account password --admins Administrators' services accounts, comma-separated -H --homeChannels Home channels to operate in, comma-separated -C --guestChannels Non-home channels to idle in, comma-separated -w --save Write configuration to file A dash (-) clears, so -C- translates to no channels, -A- to no account name, etc.
$ dub run kameloso -- --server irc.freenode.net --guestChannels "#d,#freenode" # alternatively $ git clone https://github.com/zorael/kameloso.git $ cd kameloso $ dub build $ ./kameloso --server irc.freenode.net --guestChannels "#d,#freenode"
Table of contents
- Getting started
- How to use
- Known issues
- Built with
kameloso can be built using the reference compiler dmd, which compiles very fast; and the LLVM-based ldc, which is slower but produces faster code. The stable release of the GCC-based gdc is currently based on version 2.076 and is thus too old to be used.
The package manager dub is used to facilitate compilation and dependency management. On Windows it comes bundled in the compiler archive, while on Linux it will need to be installed separately. Refer to your repositories.
$ git clone https://github.com/zorael/kameloso.git $ cd kameloso
$ dub build
This will compile the bot in the default
debug mode, which adds some extra code and debugging symbols. You can automatically skip these and add some optimisations by building it in
release mode with
dub build -b release. Mind that build times will increase. Refer to the output of
dub build --help for more build types.
See the known issues section for compilation caveats.
There are several configurations in which the bot may be built.
application, base configuration
twitch, additionally includes Twitch chat support and the Twitch streamer plugin
dev, all-inclusive development build equalling everything available, including things like more detailed error messages
All configurations come in a
twitch-lowmem, ...} that lowers compilation memory by raising compilation time, but so far they only work with ldc. (bug #20699)
List them with
dub build --print-configs. You can specify which to compile with the
-c switch. Not supplying one will make it build the default
$ dub build -c twitch
If you want to customise your own build to only compile the plugins you want to use, see the larger
dub.sdl. Simply delete the lines that relate to the plugins you want to omit.
How to use
The bot needs the account name of one or more administrators of the bot, and/or one or more home channels to operate in. Without either it's just a read-only log bot. To define these you can either specify them on the command-line, or generate a configuration file and enter them there.
$ ./kameloso --save
kameloso.conf will be created in a directory dependent on your platform.
- Linux/other Posix:
- Other unexpected platforms: fallback to current working directory
Open the file in a normal text editor. If you have your system file associations set up to open
*.conf files in an editor, you can open it by passing
You can override some configured settings with arguments on the command line, listed by calling the program with
--help. If you specify some and also add
--save, it will apply and save these changes to the configuration file, without having to manually edit it.
$ ./kameloso \ --server irc.freenode.net \ --nickname "kameloso" \ --admins "you,friend,thatguy" \ --homeChannels "#channel,#elsewhere" \ --guestChannels "#d,##networking" \ --save Configuration file written to /home/user/.config/kameloso/kameloso.conf
Later invocations of
--save will regenerate the file. It will never overwrite custom settings, only complement them with new ones. Mind however that it will delete any lines not corresponding to a currently available setting, so settings that relate to plugins that are currently not built in are silently removed.
If you have bright terminal background, the colours may be hard to see and the text difficult to read. If so, pass the
--bright argument, and/or modify the configuration file;
[Core]. The bot uses the full range of 8-colour ANSI, so if one or more colours are too dark or bright even with the right
brightTerminal setting, please refer to your terminal appearance settings. An alternative is to disable colours entirely with
More server-specific resource files will be created the first time you connect to a server. These include
users.json, in which you whitelist which accounts get to access the bot's features. Where these are stored also depends on platform; in the case of macOS and Windows they will be put in server-split subdirectories of the same directory as the configuration file, listed above. On Linux and other Posix, under
~/.local/share/kameloso (or wherever
$XDG_DATA_HOME points). As before it falls back to the working directory on other unexpected platforms.
you joined #channel kameloso sets mode +o you you | I am a fish you | s/fish/snek/ kameloso | you | I am a snek you | !quote kameloso I am a snek kameloso | Quote saved. (1 on record) you | !quote kameloso kameloso | kameloso | I am a snek you | !seen MrOffline kameloso | I last saw MrOffline 1 hour and 34 minutes ago. you | !note MrOffline About the thing you mentioned, yeah no kameloso | Note added. MrOffline joined #channel kameloso | MrOffline! you left note 28 minutes ago: About the thing you mentioned, yeah no you | !operator add bob kameloso | Added BOB as an operator in #channel. you | !whitelist add alice kameloso | Added Alice as a whitelisted user in #channel. you | !blacklist del steve kameloso | Removed steve as a blacklisted user in #channel. you | !automode add ray +o kameloso | Automode modified! ray on #channel: +o ray joined #channel kameloso sets mode +o ray you | !poll 60 snek snik kameloso | Voting commenced! Please place your vote for one of: snik, snek (60 seconds) BOB | snek Alice | snek ray | snik kameloso | Voting complete, results: kameloso | snek : 2 (66.6%) kameloso | snik : 1 (33.3%) you | https://github.com/zorael/kameloso kameloso | [github.com] GitHub - zorael/kameloso: IRC bot you | https://youtu.be/ykj3Kpm3O0g kameloso | [youtube.com] Uti Vår Hage - Kamelåså (HD) (uploaded by Prebstaroni)
Online help and commands
!help command for a summary of available bot commands, and
!help [plugin] [command] for a brief description of a specific one.
The prefix character (here
!) is configurable; refer to your generated configuration file. Common alternatives are
~, making it
[Core] prefix "!"
It can technically be any string and not just one character. It may include spaces, like
"please " (making it
please quote, ...). Prefixing commands with the bot's nickname also works, as in
kameloso: seen MrOffline. Some administrative commands only work when called this way.
Except nothing happens
Before allowing anyone to trigger any restricted functionality, it will query the server for what services account they are logged onto. For full administrative privileges you will need to be logged onto an account listed in the
admins field in the configuration file, while other users may be defined in your
users.json file. If a user is not logged onto services it is considered as not being uniquely identifiable, and as such will not be able to access features it normally might have enjoyed.
In the case of hostmasks mode, the above still applies but "accounts" are inferred from hostmasks. See the
hostmasks.json file for how to map hostmasks to would-be accounts.
To connect to Twitch servers you must first build a configuration that includes support for it, which is currently either
You must also supply an OAuth token pass (not password). These authorisation tokens are unique to your user, paired with an application. As such, you need a new one for each and every program you want to access Twitch with, this one being no exception.
Run the bot with
--set twitchbot.keygen to start the captive process of generating one. It will open a browser window, in which you are asked to log onto Twitch on Twitch's own servers. Verify this by checking the page address; it should end with
twitch.tv, with the little lock symbol showing the connection is secure.
Note: At no point is the bot privy to your login credentials! The logging-in is wholly done on Twitch's own servers, and no information is sent to any third parties. The code that deals with this is open for audit;
After entering your login and password and clicking Authorize, you will be redirected to an empty "this site can't be reached" page. Copy the URL address of it and paste it into the terminal, when asked. It will parse the address, extract your authorisation token, and offer to save it to your
kameloso.conf configuration file.
If you prefer to generate the token manually, here is the URL you need to follow. The only thing the generation process does is open it for you, and help with saving the end key to disk.
[IRCClient] nickname botaccount user ignored realName likewise [IRCBot] #account #password pass oauth:personalauthorisationtoken admins mainaccount homeChannels #mainaccount,#botaccount guestChannels #streamer1,#streamer2,#streamer3 [IRCServer] address irc.chat.twitch.tv port 6667
The Twitch SSL port is 443.
See the wiki page on Twitch for more information.
Streamer assistant bot
The streamer bot plugin is opt-in during compilation; build the
twitch configuration to compile it. Even if built it can be disabled in the configuration file under the
[TwitchBot] section. If the section doesn't exist, regenerate the file after having compiled a build configuration that includes the bot plugin. As previously alluded to, configuration file sections will not show up when generating the file if the corresponding plugin is not compiled in.
$ dub build -c twitch $ ./kameloso --set twitchbot.enabled=false --save
Assuming a prefix of "
!", commands to test are:
!poll, and other non-Twitch-specific commands.)
Note: dot "
." and slash "
/" prefixes will not work on Twitch, as they conflict with Twitch's own commands.
To disable heavier commands that access Twitch's API (currently only the
!followage command), set
[TwitchBot] in the configuration file to
Please make the bot a moderator to prevent its messages from being as aggressively rate-limited.
There is also a channel
#kameloso on freenode, but replies may be delayed.
Compiling in a non-
debug build mode might fail (bug #18026). Try
--build-mode=singleFile, which compiles one file at a time and as such lowers memory requirements, but drastically increases build times.
On Windows with dmd 2.089 and above builds may fail, either silently with no output, or with an
OutOfMemoryError being thrown. See issue #83. The workarounds are to either use the ldc compiler with
--compiler=ldc2, or to build with the
While ldc is slower to compile than the default dmd, it's not
singleFile-level slow. In addition it also produces faster binaries, so if you hit this bug ldc might be the better alternative, over
If SSL flat doesn't work at all, you may simply be missing the necessary libraries. Download and install OpenSSL from here, and opt to install to system directories when asked.
Even with SSL working, you may see errors of "Peer certificates cannot be authenticated with given CA certificates". If this happens, download this
cacert.pem file, place it somewhere reasonable, and edit your configuration file to point to it;
In Cygwin/mintty terminals, there may be garbage "
[39m" characters randomly at the beginning of lines, lines may arbitrarily break at certain lengths, text effects may spiral out of control, and more general wonkiness. It's really unreliable, and unsure how to solve it. The current workaround is to just use
cmd.exe, the Powershell console or a Windows Subsystem for Linux (WSL) terminal instead.
If the pipeline FIFO is removed while the program is running, it will hang upon exiting, requiring manual interruption with Ctrl+C. This is a tricky problem to solve as it requires figuring out how to do non-blocking reads. Help wanted.
- pipedream zero: no compiler segfaults (#18026, #20562)
- pipedream: DCC
- non-blocking FIFO
- more pairs of eyes
This project is licensed under the MIT license - see the LICENSE file for details.