IRC-kosmi-relay/docs/setup/QUICK_REFERENCE.md

Quick Reference Guide

Running the Bridge

Build and Run Locally

cd /Users/erikfredericks/dev-ai/HSO/irc-kosmi-relay
go build -o matterbridge .
./matterbridge -conf matterbridge.toml

Run with Docker

docker-compose up -d
docker-compose logs -f

Expected Output (Success)

INFO Connecting to Kosmi
INFO Extracted room ID: @yourroom
INFO No credentials provided, using anonymous access
INFO Successfully connected to Kosmi
INFO Connection succeeded (IRC)
INFO Gateway(s) started successfully. Now relaying messages

If using email/password authentication:

INFO Authenticating with email/password...
INFO ✅ Authentication successful
INFO Successfully connected to Kosmi

Key Status Indicators

Log Message	Meaning
Successfully connected to Kosmi	Native WebSocket connection established
Connection succeeded (IRC)	IRC bridge is connected
Gateway(s) started successfully	All bridges up, relay is active
✅ Using cached token	Reusing saved JWT (no browser needed)
✅ Authentication successful	Browser login completed
Kosmi connection lost unexpectedly	WebSocket dropped, auto-reconnect triggered

IRC Commands

Command	Action
!kreconnect	Reconnect Kosmi bridge
!jreconnect	Reconnect Jackbox WebSocket
!reconnect	Reconnect all non-IRC services
!votes	Show current game vote tally

See IRC.md for full details including vote syntax and ticker symbols.

Configuration

Minimal Configuration

[kosmi.myroom]
RoomURL="https://app.kosmi.io/room/@yourroom"

[irc.myserver]
Server="irc.libera.chat:6697"
Nick="kosmi-relay"
UseTLS=true

[[gateway]]
name="kosmi-irc"
enable=true

[[gateway.inout]]
account="kosmi.myroom"
channel="main"

[[gateway.inout]]
account="irc.myserver"
channel="#your-channel"

With Authentication

[kosmi.myroom]
RoomURL="https://app.kosmi.io/room/@yourroom"
Email="your-email@example.com"
Password="your-password"

With Jackbox Integration

[jackbox]
Enabled=true
APIURL="https://your-jackbox-api.example.com"
AdminPassword="your_password"
UseWebSocket=true
EnableRoomCodeImage=true

Message Format

Kosmi --> IRC

[kosmi] <username> message text

IRC --> Kosmi

[irc] <username> message text

Format is controlled by RemoteNickFormat in each bridge's config section.

File Locations

File	Purpose
bridge/kosmi/kosmi.go	Main Kosmi bridge
bridge/kosmi/graphql_ws_client.go	Native GraphQL WebSocket client
bridge/kosmi/auth.go	Anonymous login
bridge/kosmi/browser_auth.go	Chromedp browser login
bridge/kosmi/token_cache.go	JWT token caching
bridge/irc/handlers.go	IRC commands and vote detection
bridge/jackbox/client.go	Jackbox API client
bridge/jackbox/votes.go	Vote detection logic
matterbridge.toml	Runtime configuration

Common Issues

Kosmi connection fails

1. Verify RoomURL is correct and the room exists
2. Check network connectivity: curl -I https://app.kosmi.io
3. Enable debug logging: -debug flag
4. Check logs for WebSocket handshake errors

Authentication fails

1. Verify Chrome/Chromium is installed: which chromium chromium-browser google-chrome
2. Check credentials are correct
3. Delete cached token to force fresh login: rm data/kosmi_token_cache.json
4. Check for Kosmi UI changes that may break browser automation

Messages not appearing

1. Confirm both bridges are connected (check logs)
2. Verify gateway config: Kosmi channel must be "main", IRC channel must have #
3. Enable debug logging to trace message routing
4. Check for RemoteNickFormat issues

Jackbox votes not registering

1. Verify Jackbox integration is enabled in config
2. Check that an active session exists with games played
3. Confirm messages don't start with [irc] or [kosmi] prefix (relayed messages skip vote detection)

CLI Flags

./matterbridge -conf matterbridge.toml    # Specify config file
./matterbridge -debug                      # Enable debug logging
./matterbridge -muted                      # Start with Jackbox announcements muted
./matterbridge -version                    # Show version info

Mute Toggle

Toggle Jackbox announcements at runtime:

# Local
kill -SIGUSR1 $(pgrep matterbridge)

# Docker
docker kill -s SIGUSR1 kosmi-irc-relay

Docker Commands

docker-compose up -d              # Start
docker-compose down               # Stop
docker-compose restart            # Restart
docker-compose logs -f            # Follow logs
docker-compose logs --tail=100    # Last 100 lines
docker-compose build --no-cache   # Rebuild

Further Reading

• README.md -- Project overview and architecture
• IRC.md -- IRC command and voting reference
• DOCKER_QUICKSTART.md -- 5-minute Docker setup
• JACKBOX_INTEGRATION.md -- Jackbox Game Picker setup
• BROWSER_AUTH_GUIDE.md -- Email/password authentication
• MUTE_CONTROL.md -- Mute toggle guide