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.):
- 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
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.
