To use this package, run the following command in your project's root directory:
Put the following dependency into your project's dependences section:
kameloso is an IRC bot.
Current functionality includes:
- chat monitoring in bedazzling colours or mesmerising monochrome
- reporting titles of pasted URLs, YouTube video information fetch
sed-replacement of messages (
- saving notes to offline users that get played back when they come online
- channel polls,
!seen, counters, stopwatches
- automatic mode sets (e.g. auto
- works on Twitch with some additional common Twitch bot features
- more random stuff and gimmicks
All of the above are plugins and can be disabled at runtime or omitted from compilation entirely. It is modular and easy to extend. A skeletal Hello World plugin is 25 lines of code.
Please report bugs. Unreported bugs can only be fixed by accident.
-n --nickname Nickname -s --server Server address [irc.libera.chat] -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 --bright Adjust colours for bright terminal backgrounds --monochrome Use monochrome output --save Write configuration to file
Pre-compiled binaries for Windows and Linux can be found under Releases.
dub run kameloso -- --server irc.libera.chat --guestChannels "#d" # alternatively, guaranteed latest git clone https://github.com/zorael/kameloso.git cd kameloso dub build ./kameloso --server irc.libera.chat --guestChannels "#d"
If there's anyone talking it should show up on your screen.
Table of contents
- Getting started
- How to use
- Example use
- Further help
- Known issues
- Built with
Grab a pre-compiled binary from under Releases; alternatively, download the source and compile it yourself.
kameloso is written in D. It can be built using the reference compiler dmd, which compiles very fast; and the LLVM-based ldc, which is slower at compiling but produces faster code. See here for an overview of the available compiler vendors.
You need one based on D version 2.084 or later (January 2019). For ldc this is version 1.14. Sadly, the stable release of the GCC-based gdc is currently based on version 2.076 and is thus too old to be used.
If your repositories (or other software sources) don't have compilers new enough, you can use the official
install.sh installation script to download current ones, or any version of choice.
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 may need to be installed separately. Refer to your repositories.
SSL libraries on Windows
See the known issues section on Windows for information on libraries needed to connect to SSL servers and to allow plugins to access the web via
git clone https://github.com/zorael/kameloso.git
It can also be downloaded as a
This will compile the bot in the default debug mode, which adds some extra code and debugging symbols. You can automatically omit these and perform some optimisations by building it in release mode with
dub build -b release. Mind that build times will increase accordingly. Refer to the output of
dub build --help for more build types.
There are several configurations in which the bot may be built.
application, base configuration
twitch, additionally includes Twitch chat support and the Twitch bot plugin
dev, all-inclusive development build equalling everything available, including things like more detailed error messages
All configurations come in
-lowmem variants (e.g.
twitch-lowmem, ...) that lower compilation memory required at the cost of increasing compilation time, but so far they only work with ldc. (bug #20699)
List configurations 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 add a character to the line corresponding to the plugin(s) you want to omit, thus invalidating the version identifiers. Mind that disabling any of the "service" plugins may/will break the bot in subtle ways.
How to use
The bot ideally wants 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, which is also fine. To define these you can either specify them on the command line, with flags listed by calling the program with
--help, or generate a configuration file with
--save and enter them there.
kameloso.conf will be created in a directory dependent on your platform.
- Linux and other Posix:
$XDG_CONFIG_HOMEpoints to; XDG standards are assumed)
Open the file in a normal text editor.
As a shortcut you can pass
--geditto attempt to open it in a graphical editor, or
--editto open it in your default terminal one, as defined in the
You can make changes to your configuration file in-place by specyfing some at the command line and adding
kameloso \ --server irc.libera.chat \ --nickname "kameloso" \ --admins "you" \ --homeChannels "#mychannel" \ --guestChannels "#d,##networking" \ --monochrome --save [12:34:56] Configuration written to /home/user/.config/kameloso/kameloso.conf
Settings not touched will keep their values.
kameloso's text colours are by default set to go well with dark terminal backgrounds. If you have a bright background, text may be difficult to read (white on white), depending on your terminal emulator. If so, pass the
--bright argument, and/or modify the configuration file;
[Core]. The bot uses 7 colours out 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 are allowed to access the bot's features on a per-channel basis. 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
$HOME/.local/share/kameloso (or wherever
$XDG_DATA_HOME points to; XDG standards remain assumed).
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. MrOnline | !note MrOffline About the thing you mentioned, yeah no kameloso | Note added. MrOnline left #channel MrOffline joined #channel kameloso | MrOffline! MrOnline left note 4 hours and 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 | !oneliner add info @$nickname: for more information just use Google kameloso | Oneliner !info added. you | !oneliner add vods See https://twitch.tv/zorael/videos for $streamer's on-demand videos (stored temporarily) kameloso | Oneliner !vods added. you | !oneliner add source I am $bot. Peruse my source at https://github.com/zorael/kameloso kameloso | Oneliner !source added. you | !info kameloso | @you: for more information just use Google you | !vods kameloso | See https://twitch.tv/zorael/videos for Channel's on-demand videos (stored temporarily) you | !commands kameloso | Available commands: !info, !vods, !source you | !oneliner del vods kameloso | Oneliner !vods removed. 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) <context: playing a video game> you | !counter add deaths kameloso | Counter deaths added! Access it with !deaths. you | !deaths+ kameloso | deaths +1! Current count: 1 you | !deaths+3 kameloso | deaths +3! Current count: 4 you | !deaths kameloso | Current deaths count: 4 you | !deaths=0 kameloso | deaths count assigned to 0! you | !stopwatch start kameloso | Stopwatch started! you | !stopwatch kameloso | Elapsed time: 18 minutes and 42 seconds you | !stopwatch stop kameloso | Stopwatch stopped after 1 hour, 48 minutes and 10 seconds.
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 shorthand
!help !command also works.
The command prefix (here
!) is configurable; refer to your configuration file. Common alternatives are
~ (tilde) and
?, making it
[Core] prefix "!"
It can technically be any string and not just one character. It may include spaces if enclosed within quotes, like
"please " (making it
please quote, ...). Additionally, prefixing commands with the bot's nickname also works, as in
kameloso: seen MrOffline. This is to be able to disambiguate between several bots in the same channel. Moreover, some administrative commands only work when called this way.
Except nothing happens
Before allowing anyone to trigger any restricted functionality, the bot will query the server for what services account the accessing user is logged onto, if not already known. For full administrative privileges you will need to be logged in with 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 cannot be resolved to an account.
In the case of hostmasks mode, the above still applies but "accounts" are derived from hostmasks. See the Admin plugin
!hostmaskcommand (and the
hostmasks.jsonfile) for how to map hostmasks to would-be accounts. Hostmasks are a weaker solution to user identification but not all servers may offer services. See the wiki entry on hostmasks for more information.
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 to be confused with
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.
Run the bot with
--set twitch.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 Twitch 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" or "
unable to connect" 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 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 automate saving the end key to disk.
[IRCClient] nickname botaccount user ignored realName likewise [IRCBot] #account #password pass personaloauthauthorisationtoken admins mainaccount homeChannels #mainaccount,#botaccount #guestChannels [IRCServer] address irc.chat.twitch.tv port 6697
The Twitch SSL port is 6697 (and 443). For non-encrypted traffic, use the default port 6667.
See the wiki page on Twitch for more information.
Please make the bot a moderator to prevent its messages from being as aggressively rate-limited.
Assuming a prefix of
!, commands to test are:
!stopwatch, and other non-Twitch-specific commands. Try
!help or the wiki.
/(slash) prefixes will not work on Twitch.
For more information and help, first see the wiki.
If you still can't find what you're looking for, or if you have suggestions on how to improve the bot, you can...
kameloso uses OpenSSL to establish secure connections. It is the de facto standard SSL library in the Posix sphere (Linux, macOS, ...), but not so on Windows. If you run into errors about missing SSL libraries when attempting to connect on Windows, supply the
--get-openssl flag to download and launch the installer for OpenSSL for Windows, and opt to install to Windows system directories when asked.
- pipedream zero: no compiler segfaults (#18026, #20562)
- please send help: Windows Secure Channel SSL
- split Twitch timers into own plugin
- Twitch web server to catch auth key
- help plugin descriptions? multiple syntax entries?
- more pairs of eyes
This project is licensed under the Boost Software License 1.0 - see the LICENSE10.txt file for details.
- Registered by JR
- 3.0.1 released 4 months ago
- Copyright © 2016-2022, JR
- arsd-official:http, dialect, requests, arsd-official:dom, lu
3.3.0 2022-Jul-24 3.2.1 2022-Jun-15 3.2.0 2022-Jun-14 3.1.0 2022-May-10 3.0.1 2022-Apr-30
- Download Stats:
0 downloads today
1 downloads this week
1 downloads this month
34 downloads total
- Short URL: