Current plugins - zorael/kameloso GitHub Wiki

This is a list of the current plugins as of 2024-01-14.

Assuming the default prefix of !, as defined as prefix under [Core] in the configuration file, commands can be triggered with !command (with some exceptions). Some commands may be gated to only be available in debug builds.

Use the !help command to get an accurate list of all the plugins currently available in the build configuration you compiled, and the commands they offer.

The following list assumes a prefix of !.

In places where a duration is required, you can either enter an amount in seconds, or in an abbreviated form *d*h*m*s. As in, 2h, 1m20s, 1d2h3m4s, etc.

Table of contents

Section Description
admin Administration and debugging of the bot
automode Automatically assigning modes to users
bash Fetches bash.org quotes from bashforever.com
chatbot Legacy
counter Serving counters; words with values that you can increment and decrement
help Providing an online listing of all commands
note Saving notes to offline users, replaying them when they come online
oneliner Define oneliners; commands that just repeat one or more lines of text
pipeline Piping commands to the bot from a terminal (Linux/macOS/other Posix)
poll Channel polls
printer Monitoring chat in your terminal
quote Maintaining a database of user quotes
same Example "same" plugin
sedreplace s/this/that/ substitution
seen !seen; when a user was last seen online
stopwatch Primitive stopwatches
time Reporting what time it is in a given timezone
timer Timed announcements
twitch Twitch-specific commands and features
webtitle Reporting titles of pasted URLs

admin

This is a plugin with administrative and debugging features. It is not mandatory in any sense but it does allow for some remote control of the bot. It can be safely disabled or removed if not needed, but then some changes would only be possible to change by manually editing resource files. Some commands are only available if the program was compiled in debug mode.

It supports the following commands (where [bot] is the bot's current nickname):

  • user: Query the bot for information about a user, output to the local terminal.
    • [bot]: user [nickname]
  • save: Save current configuration to disk.
    • [bot]: save
  • users: Query the bot for information about all users known to the Admin plugin, output to the local terminal.
    • [bot]: users
  • sudo: Send a text string to the server (knowledge of IRC server strings necessary).
    • [bot]: sudo [raw string]
  • quit: Ask the bot to terminate cleanly.
    • [bot]: quit [optional reason]
  • home: Add or remove a home directory for the bot to operate in.
    • !home add [channel]
    • !home del [channel]
    • !home list
  • staff: List, add or remove an account (or nickname) to/from the list of owners of the current channel.
    • !staff add [account or nickname]
    • !staff del [account or nickname]
    • !staff list
  • operator: List, add or remove an account (or nickname) to/from the list of operators/moderators allowed to trigger bot commands gated behind operator checks.
    • !operator add [account or nickname]
    • !operator del [account or nickname]
    • !operator list
  • elevated: List, add or remove an account (or nickname) to/from the list of people allowed to trigger bot commands gated behind elevated checks.
    • !elevated add [account or nickname]
    • !elevated del [account or nickname]
    • !elevated list
  • whitelist: List, add or remove an account (or nickname) to/from the whitelist of people allowed to trigger bot commands gated behind whitelist checks.
    • !whitelist add [account or nickname]
    • !whitelist del [account or nickname]
    • !whitelist list
  • blacklist: List, add or remove an account (or nickname) to/from the blacklist of people who may explicitly not trigger the bot.
    • !blacklist add [account or nickname]
    • !blacklist del [account or nickname]
    • !blacklist list
  • hostmask: List, add or remove a hostmask-"account" binding. For use on servers that lack services.
    • !hostmask add [account] [nickname!ident@address hostmask]
    • !hostmask del [nickname!ident@address hostmask]
    • !hostmask list
  • whoami: Sends what we know of the inquiring user.
    • !whoami
  • printraw: Toggle printing all incoming raw IRC strings.
    • [bot]: printraw
  • printbytes: Toggle printing all incoming IRC messages split into bytes, for diagnostics.
    • [bot]: printbytes
  • join: Tell the bot to join a channel (but not set it as a home).
    • [bot]: join [channel]
  • part: Tell the bot to part from a channel.
    • [bot]: part [channel]
  • set: Change a plugin's setting. Enabling or disabling a plugin this way yields undefined behaviour.
    • [bot]: set [plugin].[setting]=[value]
  • get: Fetches the value of a plugin's setting, or a list of all its setting if no settings name supplied.
    • [bot]: get [plugin].[setting]
    • [bot]: get [plugin]
  • auth: Reauthenticate with services.
    • [bot]: auth
  • status: Query the bot for some basic internal bot status, output to the local terminal.
    • [bot]: status
  • reload: Forces plugins to reload. What that does is up to implementation, but generally they reload resources from disk.
    • !reload
  • summary: Tells the bot to print a connection summary to the local terminal.
    • [bot]: summary
  • bus: Sends an internal bus message to plugins.
    • [bot]: bus [message header] [optional content]
  • cycle: Cycles a channel (parting it and rejoining it immediately afterwards.
    • [bot]: cycle [optional channel] [optional delay] [optional join key]
  • reconnect: Disconnects from and immediately reconnects to the server.
    • [bot]: reconnect [optional quit message]
  • reexec: Re-executes the program.
    • [bot]: reexec [optional quit message]

automode

The Automode plugin automatically changes modes of users in channels as per saved definitions. Definitions are saved in a JSON file.

It supports the following commands:

  • automode: Add new, list existing or clear all automodes for a user, in the context of the current channel.
    • !automode add [account] [mode]
    • !automode clear [account]
    • !automode list
  • op: Request automodes to be applied to you, if they weren't for some reason.
    • !op

Examples

!automode add friend +o
!automode add associate +v

bash

The Bash plugin fetches bash.org quotes from bashforever.com and sends them to a channel (or to a private query). It can fetch a random one or a specific one by quote ID.

It supports the following commands:

  • bash: Fetch a random or specified bash.org quote and echoes it to the current channel.
    • !bash [optional quote ID number]

chatbot

The Chatbot plugin provides common chat functionality. This includes magic 8ball and some other toy miscellanea. It is the oldest part of the bot.

It supports the following commands:

  • say/echo: Repeats text. Amazing.
    • !say [text]
    • !echo [text]
  • DANCE: Dances.
    • DANCE!

counter

The Counter plugin allows you to create runtime counter commands to keep count of how many times something has occurred. This can be used to track deaths in video game streams, for instance.

It supports the following commands:

  • counter: Manages counters.
    • !counter add [counter word]
    • !counter del [counter word]
    • !counter format [counter word] [one of ?, +, - and =] [new format pattern]
    • !counter list
  • [word]: Increments, decrements or assigns a counter a specific value.
    • ![word]
    • ![word]+[optional number]
    • ![word]-[optional number]
    • ![word]=[number]

Examples

you    | !counter add deaths
friend | !deaths+
other  | !deaths+2
third  | !deaths=0

You can customise your own pattern of the messages used with counter format. There is one pattern for queries (?), increments (+), decrements (-), and one for assignments (=). To specify a pattern for queries, you would simply issue a command like thus:

!counter format deaths ? The current deaths count is $count.

Then replace ? with + to modify the increment pattern, - to modify the decrement pattern, and = to modify the assignment pattern. Assigning a pattern to a single dash (-) resets it to the default pattern. Assigning it a pattern of "" clears the pattern and disables output.

Some keywords/tokens in patterns are automatically replaced with more helpful values.

Token Description
$step By how much a counter increment/decrement modified the count.
$count The current count, post-any increments or decrements.
$word The counter word.
$bot Bot nickname, or display name on Twitch.
$botNickname Bot nickname.
$channel Channel name.
$streamer (Twitch) Streamer display name.
$streamerNickname (Twitch) Streamer nickname.
$nickname Nickname of user invoking the counter.
$displayName (Twitch) Display name of user invoking the counter.

help

The Help plugin lists the available bot commands in a private query message. It was part of the Chatbot plugin but has since been broken out into its own plugin.

It supports the following commands:

  • help: Send a list of all* available commands to the requester, in the channel or in a private query message depending on applicability and configuration.
    • !help
    • !help [plugin]
    • !help [plugin] [command]
    • !help ![command]

"Soft" commands, like counters and oneliner triggers, are not included in the listing.

note

The Notes plugin allows people to leave messages to each other, for offline communication and such.

It supports the following commands:

  • note: Leave a note to a user, to be replayed when they come online.
    • !note [account] [text]

Examples

you    | !note friend Call me regarding the thing
[...]
friend | !note you Learn to pick up

oneliner

The Oneliner plugin listens for custom commands and replies with preset lines. With it, you can (for instance) define a custom !bot command that parrots a message with information about the bot. Custom commands are per-channel and defined at runtime, not by modifying the source as would otherwise be the case.

[type] may be either random or ordered, and dictates -- in presence of multiple lines -- whether a random line will be selected on each invocation or if it will echo them in an ordered fashion.

It supports the following commands:

  • oneliner: Add or remove a oneliner.
    • !oneliner new [trigger] [type] [optional cooldown]
    • !oneliner add [trigger] [text]
    • !oneliner alias [trigger] [existing trigger to alias]
    • !oneliner modify [trigger] [type] [optional cooldown]
    • !oneliner edit [trigger] [position] [new text]
    • !oneliner insert [trigger] [position] [text]
    • !oneliner del [trigger] [optional position]
    • !oneliner list
  • commands: List current (non-alias) oneliners.
    • !commands

This functionality was historically part of the Twitch bot plugin.

Some keywords/tokens in messages are automatically replaced with more helpful values.

Token Description
$bot Bot nickname, or display name on Twitch.
$botNickname Bot nickname.
$sender Nickname or display name of the user invoking the oneliner.
$senderNickname Nickname of the user invoking the oneliner.
$channel Channel name.
$streamer (Twitch) Streamer display name.
$streamerAccount (Twitch) Streamer account name.
$args All arguments passed to the oneliner (the abc def ghi in !foo abc def ghi)
$arg0 The trigger word used to invoke the oneliner, with original casing.
$argn The nth argument (1-9) passed to the oneliner, or an empty string if none.
$argnname The nth argument (1-9) passed to the oneliner intepreted as a user name, or an empty string if none.
$random(i..n) or merely $random Generates a number between i inclusive and n exclusive, or a default 0-99.

Example 8ball oneliner

With responses taken from Wikipedia;

!oneliner new 8ball random 3s
!oneliner add 8ball It is certain
!oneliner add 8ball It is decidedly so
!oneliner add 8ball Without a doubt
!oneliner add 8ball Yes, definitely
!oneliner add 8ball You may rely on it
!oneliner add 8ball As I see it, yes
!oneliner add 8ball Most likely
!oneliner add 8ball Outlook good
!oneliner add 8ball Yes
!oneliner add 8ball Signs point to yes
!oneliner add 8ball Reply hazy try again
!oneliner add 8ball Ask again later
!oneliner add 8ball Better not tell you now
!oneliner add 8ball Cannot predict now
!oneliner add 8ball Concentrate and ask again
!oneliner add 8ball Don't count on it
!oneliner add 8ball My reply is no
!oneliner add 8ball My sources say no
!oneliner add 8ball Outlook not so good
!oneliner add 8ball Very doubtful
!oneliner alias eightball 8ball

pipeline

The Pipeline plugin reads from a local named pipe (FIFO) for messages to send to the server. It is only available on Posix-like systems (Linux, macOS, ...).

A new feature is the possibility to send messages directly to plugins, as another form of remote control. Piped messages starting with a # octothorpe are broadcast as messages aimed for a plugin. Much of the admin plugin can be controlled this way.

Examples

$ echo 'PRIVMSG #d :Hello world!' > [email protected]
$ echo '#admin status' > [email protected]
$ echo '#admin user harbl' > [email protected]
$ echo '#admin save' > [email protected]
$ echo '#admin hostmask add kameloso kameloso*[email protected].*' > [email protected]
$ echo '#admin set printer.filterMost=false' > [email protected]
$ echo '#admin reexec' > [email protected]
$ echo '#admin gc.stats' > [email protected]
[...]

(These are undocumented; use the source, Luke!)

It has no commands.

poll

The Poll plugin allows you to start votes/polls for the users to vote on. You may have any number of poll choices, as long as they're more than one.

It supports the following commands:

  • poll: Instigate a poll between two or more options, or stops an ongoing one. Pass abort to abort (discarding votes), or end to end early (and show results).
    • !poll [duration] [option1] [option2] [option3] [...]
    • !poll abort
    • !poll end

Examples

you    | !poll 300s burgers pizza salads
friend | pizza
other  | burgers
third  | pizza

printer

The Printer plugin takes incoming events and prints them to the local terminal, formatted and optionally in colour.

This used to be part of the core program, but with UDAs it's easy to split off into its own plugin.

It has no commands.

quote

The Quotes plugin provides the ability to save and replay user quotes. A search term may be supplied to find a specific quote, or a quote may be replaced based on its given internal index.

Nicknames need not be supplied on Twitch. All commands assume that quotes were meant for the owner of the channel.

These are not currently automatically replayed, such as when a user joins a channel, but can rather be actively queried by use of the quote verb.

It supports the following commands:

  • quote: Fetch and echo a quote for a specified user. If a new quote is supplied, instead adds it.
    • !quote [nickname]
    • !quote [nickname] [#index]
    • !quote [nickname] [search terms]
  • addquote: Adds a new quote.
    • !addquote [nickname] [quote text]
  • modquote: Modifies the text of an existing quote. Not specifying a new text will print the quote as it currently is.
    • !modquote [nickname] [quote index] [new quote text]
  • delquote: Removes a quote from the quote database.
    • !delquote [nickname] [quote index]
  • mergequotes: Merges the quotes of two users, copying them from the source into the target and removing the originals.
    • !mergequotes [source] [target]

Examples

!addquote friend I thought what I'd do was, I'd pretend I was one of those deaf-mutes.
!quote friend

same

The example Same plugin shows how you can write event handlers that listen to any text, rather than just wait for !commands.

It has no commands, but will react to someone saying "same". The purpose of it is purely educational.

sedreplace

The SedReplace plugin stores a buffer of the last said line of every user, and if a new message comes in with a sed-replace-like pattern in it, tries to apply it on the original message as a regex replace.

It does not take any commands per se but rather listens for messages with patterns matching s/foo/bar/ and similar. It supports a delimiter of /, |, #, @, , _ and ;, but more can be trivially added.

Examples

I am chatting on Librea.Chat
s/Librea/Libera/

seen

The Seen plugin implements !seen functionality; the ability for someone to query when a given nickname was last seen online.

Note: By default only users in your home channels are tracked. To monitor and record all users (even those in guest channels), the dub.sdl file will have to be modified and the OmniscientSeen version enabled.

It supports the following commands:

  • seen: Query the bot for when a user was last seen.
    • !seen [nickname]

stopwatch

The Stopwatch plugin allows you to create stopwatch-like timers, to get how much time passed between the creation of one and the cessation of it.

It supports the following commands:

  • stopwatch: Manages stopwatches.
    • !stopwatch start
    • !stopwatch stop [optional stopwatch ID] (requires operator privileges for IDs other than your own)
    • !stopwatch status [optional stopwatch ID]
    • !stopwatch
    • !stopwatch clear (requires operator privileges)

time

The Time plugin allows you to query what time it is in a given timezone. If no timezone was specified, the time local to the bot is reported, alternatively a specific timezone if overridden in a resource file (per channel).

It supports the following commands:

  • time: Reports the time.
    • !time
    • !time [optional timezone]
  • setzone: Overrides the time zone time is reported in when no explicit timezone is supplied.
    • !setzone [timezone]

timer

The Timer plugin allows you to create periodical announcement timers that echo lines of text at regular intervals. "Regular intervals" are counted by time and by channel activity (messages seen). A timer may therefore have a periodicity of "100 messages and 600 seconds", with which it would repeat after seeing 100 messages and ten minutes passing ...provided you passed both as [condition] when creating it. If you pass either, it repeats after seeing 100 messages or ten minutes pass.

[type] may be either random or ordered, and dictates -- in presence of multiple lines -- whether a random line will be selected on each announcement or if it will echo them in an ordered fashion.

It supports the follwing commands:

  • timer: Manages timers.
    • !timer new [name] [type] [condition] [message count threshold] [time threshold] [optional stagger message count] [optional stagger time]
    • !timer modify [name] [type] [condition] [message count threshold] [time threshold] [optional stagger message count] [optional stagger time]
    • !timer add [name] [text]
    • !timer insert [name] [position] [text]
    • !timer edit [name] [position] [new text]
    • !timer del [name] [optional line number]
    • !timer suspend [name]
    • !timer resume [name]
    • !timer list

Some keywords/tokens in timer messages are automatically replaced with more helpful values.

Token Description
$bot Bot nickname, or display name on Twitch.
$botNickname Bot nickname.
$channel Channel name.
$streamer (Twitch) Display name of broadcaster.
$streamerAccount (Twitch) Account name of broadcaster.
$random(i..n) or merely $random Generates a number between i inclusive and n exclusive, or a default 0-99.

Example timer

This one cycles through two messages with a periodicity of 100 messages and 10 minutes.

!timer new vods ordered both 100 10m 0
!timer add vods I am on YouTube! Catch my VODs at https://youtube.com/@SomeStreamer
!timer add vods VODs are also on Twitch! https://twitch.tv/somestreamer/videos/all
!timer suspend vods

twitch

The Twitch plugin is a basic streamer bot, for use to help audiences when streaming on Twitch. Note that most other plugins remain available even on Twitch servers.

It supports the following commands:

  • uptime: Query the bot for how long the stream has ben ongoing.
    • !uptime
  • followage: Displays how long you have been following the current channel, if at all. Alternatively, how long the passed user has been following.
    • !followage [optional nickname]
    • !followage [nickname]
  • ecount: Reports how many times an emote has been seen in the channel. Note that only Twitch's own emotes are supported.
    • !ecount [emote]
  • watchtime: Reports how long a user has been watching the channel's streams, in total. An optional nickname may be supplied.
    • !watchtime [optional nickname]
    • !watchtime [nickname]
  • repeat/spam: Repeats a message n number of times, spamming the chat with something. The maximum amount of times is hardcoded to 10.
    • !repeat [times] [text]
    • !spam [times] [text]
  • vanish/poof: Lets a viewer clear the chat of their own messages by timing them out briefly.
    • !vanish
    • !poof
  • nuke: Deletes recent messages containing a supplied word or phrase.
    • !nuke [word or phrase]
  • songrequest: Requests songs by adding one to a YouTube or Spotify playlist the streamer then plays in the background.
    • !songrequest [YouTube link, YouTube video ID, Spotify link or Spotify track ID]
  • settitle: Sets the channel title.
    • !settitle [title text]
  • setgame: Sets the current game. A game name of 0 resets it to no game. The name must match what it's called on Twitch; substring matches do not work.
    • !setgame [game name]
  • commercial: Plays a commercial with the given duration in seconds. Must be one of 30, 60, 120, 150 or 180.
    • !commercial [length]
  • startpoll: Starts a Twitch poll. Experimental, needs help from an affiliate.
    • !startpoll "[poll title between quotes]" [duration] [choice1] [choice2] [...]
  • endpoll: Ends a currently ongoing Twitch poll.
    • !endpoll
  • shoutout: Gives a shoutout to another streamer, just like the official /shoutout command does.
    • !shoutout [nickname] [optional number of times to spam]
  • subs: Reports how many subscribers the channel has.
    • !subs

webtitle

The Webtitles plugin catches HTTP URL links in a channel, connects to its server and and streams the web page itself, looking for the web page's title. This is then reported to the originating channel or private query.

It does not take any commands but rather listens for messages that look like HTTP URLs.