IRC-kosmi-relay/docs/IRC.md

IRC Command Reference

This document covers everything available to IRC users when interacting with the Kosmi-IRC relay bot. All commands and vote syntax work in any channel the bot is present in.

Commands

Commands are typed as regular messages in IRC. They are not relayed to other bridges -- the bot consumes them and acts on them directly.

There is no permission system; any user in the channel can issue any command.

!kreconnect

Force-reconnect the Kosmi bridge. Useful if the Kosmi WebSocket has silently dropped.

Response: Reconnecting Kosmi... (sent to the channel immediately)

The reconnection happens asynchronously. If it fails, errors appear only in the bot's logs.

!jreconnect

Force-reconnect the Jackbox Game Picker WebSocket. Only meaningful if the Jackbox integration is enabled.

Response: Reconnecting Jackbox...

!reconnect

Reconnect all non-IRC services (Kosmi and Jackbox) at once.

Response: Reconnecting all services...

!votes

Query the current vote tally for the game being played right now in the active Jackbox session.

Response (broadcast to all bridges -- IRC, Kosmi, etc.):

🗳️ Fibbage 4 • Today: 5👍 2👎 (Score: 3) • All-time: 46👍 3👎 (Score: 43)

Requirements:

• Jackbox integration must be enabled
• An active Jackbox session must exist
• A game must currently have status "playing" in that session

If any of these conditions are not met, the command is silently consumed (errors appear only in bot logs).

---

Voting

Vote detection runs automatically on every non-relayed message. Votes are sent to the Jackbox Game Picker API when the integration is enabled and a session is active.

Current Game Votes

Type anywhere in a message:

Syntax	Effect
thisgame++	Upvote the currently playing game
thisgame--	Downvote the currently playing game

• Case-insensitive (ThisGame++, THISGAME++, etc. all work)
• Can appear anywhere in the message text
• The message is still relayed to other bridges as normal chat

Ticker Symbol Votes

Vote on a specific game by its ticker symbol:

Syntax	Effect
SYMBOL++	Upvote the game identified by SYMBOL
SYMBOL--	Downvote the game identified by SYMBOL

• Symbols are 2-4 alphanumeric characters
• Case-insensitive (qpl3++ and QPL3++ are equivalent)
• The symbol must exist in the ticker table below
• The message is still relayed to other bridges as normal chat

Ticker Symbol Table

Symbol	Game
BC	Bomb Corp.
BDTS	Bidiots
BR	Blather 'Round
BRKT	Bracketeering
CH	Cookie Haus
CU	Champ'd Up
CVDL	Civic Doodle
DD	Dirty Drawful
DCTN	Dictionarium
DOOM	Doominate
DRM	Dodo Re Mi
DRWA	Drawful Animate
DRWF	Drawful
EW	Earwax
FANL	Fakin' It All Night Long
FBG2	Fibbage 2
FBG3	Fibbage 3
FBG4	Fibbage 4
FBXL	Fibbage XL
FI	Fakin' It!
FT	Fixy Text
GSPN	Guesspionage
HPNT	Hypnotorious
HRSY	Hear Say
JB	Joke Boat
JJ	Job Job
JNKT	Junktopia
LMF	Let Me Finish
LOT	Legends of Trivia
LS	Lie Swatter
MSM	Monster Seeking Monster
MVC	Mad Verse City
NNSR	Nonsensory
PS	Patently Stupid
PTB	Push the Button
QLXL	Quiplash XL
QPL2	Quiplash 2
QPL3	Quiplash 3
QXRT	Quixort
RM	Role Models
ROOM	Roomerang
SS	Survey Scramble
SPCT	Suspectives
STI	Survive the Internet
STR	Split the Room
TJ	Time Jinx
TKO2	Tee K.O. 2
TKOX	Tee K.O. T-Shirt Knock Out
TMP1	Trivia Murder Party
TMP2	Trivia Murder Party 2
TP	Talking Points
TPM	The Poll Mine
TWEP	The Wheel of Enormous Proportions
WD	Weapons Drawn
WS	Word Spud
YDK1	You Don't Know Jack 2015
YDKJ	You Don't Know Jack Full Stream
ZPDM	Zeeple Dome

---

Behavior Notes

Loop Prevention

Messages that begin with [irc] or [kosmi] (case-insensitive) are treated as relayed from another bridge. Vote detection is skipped for these messages to prevent duplicate votes when the same text passes through multiple bridges.

Command vs. Vote Processing Order

1. Vote detection runs first (on all non-relayed messages)
2. ! commands are checked next
3. If the message is a ! command, it is consumed and not relayed
4. If the message is not a command, it is relayed to other bridges

This means a vote phrase in a normal message (like "nice game thisgame++") both registers the vote and gets relayed. But !votes only triggers the votes query -- it is not relayed.

What IRC Users See from Other Bridges

Source	Format
Kosmi user message	[kosmi] <username> message text
Jackbox game announcement	System message (e.g. 🎮 Coming up next: Fibbage 4!)
Jackbox room code	System message with room code (may include image link)
!votes result	🗳️ Title • Today: X👍 Y👎 (Score: Z) • All-time: X👍 Y👎 (Score: Z)
Reconnect confirmation	Plain text from "system" (e.g. Reconnecting Kosmi...)

The [kosmi] prefix format is configurable via RemoteNickFormat in matterbridge.toml.

Requirements for Jackbox Features

All Jackbox-related functionality (votes, !votes, game announcements, room codes) requires:

1. [jackbox] section in config with Enabled=true
2. Valid APIURL and AdminPassword
3. An active Jackbox session on the API
4. A game currently being played (for !votes and vote detection)

When the Jackbox integration is disabled or no session is active, vote syntax is ignored and !votes produces no output.