IRC-kosmi-relay/QUICKSTART.md

Quick Start Guide

Get the Kosmi-IRC bridge running in minutes!

Prerequisites

• Go 1.21 or higher
• Chrome/Chromium browser installed (for headless browser automation)
• Access to a Kosmi room
• (Optional) IRC server access for full relay

Step 1: Test Kosmi Connection

First, verify the bridge can connect to Kosmi:

# Build the test program
go build -o test-kosmi ./cmd/test-kosmi

# Run with your Kosmi room URL
./test-kosmi -room "https://app.kosmi.io/room/@hyperspaceout" -debug

You should see output like:

INFO[...] Starting Kosmi bridge test
INFO[...] Launching headless Chrome for Kosmi connection
INFO[...] Injecting WebSocket interceptor (runs before page load)...
INFO[...] Navigating to Kosmi room: https://app.kosmi.io/room/@hyperspaceout
INFO[...] ✓ WebSocket hook confirmed installed
INFO[...] Status: WebSocket connection intercepted
INFO[...] Successfully connected to Kosmi via Chrome
INFO[...] Listening for messages... Press Ctrl+C to exit

Test it: Send a message in the Kosmi room from your browser. You should see it appear in the terminal like:

INFO[...] Received message: [00:02:51] username: [Kosmi] <username> your message here

Step 2: Integrate with Full Matterbridge

Option A: Copy into Existing Matterbridge

If you already have Matterbridge:

# Navigate to your Matterbridge directory
cd /path/to/matterbridge

# Copy the Kosmi bridge
cp -r /path/to/irc-kosmi-relay/bridge/kosmi bridge/

# Copy the bridge registration
cp /path/to/irc-kosmi-relay/gateway/bridgemap/bkosmi.go gateway/bridgemap/

# Add dependencies
go get github.com/chromedp/chromedp@v0.11.2
go mod tidy

# Build
go build

Option B: Use This Repository

This repository has a minimal Matterbridge structure. To add IRC support:

1. Copy IRC bridge from Matterbridge:

   # From the Matterbridge repo
   cp -r bridge/irc /path/to/irc-kosmi-relay/bridge/
   cp gateway/bridgemap/birc.go /path/to/irc-kosmi-relay/gateway/bridgemap/
   

2. Update dependencies:

   cd /path/to/irc-kosmi-relay
   go mod tidy
   

Step 3: Configure

Edit matterbridge.toml:

# Kosmi configuration
[kosmi.hyperspaceout]
RoomURL="https://app.kosmi.io/room/@hyperspaceout"

# IRC configuration
[irc.libera]
Server="irc.libera.chat:6667"
Nick="kosmi-bot"
UseTLS=false

# Gateway to connect them
[[gateway]]
name="kosmi-irc-relay"
enable=true

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

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

Important: Replace:

• https://app.kosmi.io/room/@hyperspaceout with your Kosmi room URL
• #your-channel with your IRC channel

Step 4: Run

./matterbridge -conf matterbridge.toml

Or with debug logging:

./matterbridge -conf matterbridge.toml -debug

Step 5: Test the Relay

1. Kosmi → IRC: Send a message in Kosmi. It should appear in IRC as:

   [Kosmi] <username> your message here
   

2. IRC → Kosmi: Send a message in IRC. It should appear in Kosmi as:

   [IRC] <username> your message here
   

Troubleshooting

Test program doesn't connect

Check:

• Is Chrome/Chromium installed and accessible?
• Is the room URL correct?
• Can you access app.kosmi.io from your network?
• Try with -debug flag for more details

Solution:

# Test Chrome installation
which google-chrome chromium chromium-browser

# Test network connectivity
curl -I https://app.kosmi.io

# Run with debug
./test-kosmi -room "YOUR_ROOM_URL" -debug

Messages not relaying

Check:

• Are both bridges connected? Look for "Successfully connected" in logs
• Is the gateway configuration correct?
• Are the channel names correct?

Solution:

# Run with debug to see message flow
./matterbridge -conf matterbridge.toml -debug

# Look for lines like:
# "Received message from Kosmi"
# "Forwarding to Matterbridge"
# "Sending to IRC"

"Room ID extraction failed"

Check: Room URL format

Supported formats:

• https://app.kosmi.io/room/@roomname
• https://app.kosmi.io/room/roomid
• @roomname
• roomid

Solution: Use the full URL from your browser's address bar

Messages not appearing from Kosmi

Check:

• Is the WebSocket hook installed? Look for "✓ WebSocket hook confirmed installed"
• Is the WebSocket connection detected? Look for "Status: WebSocket connection intercepted"
• Are messages being captured? Enable debug logging to see message processing

Solution: The bridge uses headless Chrome with a WebSocket interceptor that runs before page load. This is critical for capturing messages. The implementation uses Page.addScriptToEvaluateOnNewDocument to ensure the hook is installed before any page JavaScript executes.

If messages still aren't appearing:

1. Check Chrome console logs in debug mode
2. Verify the room URL is correct
3. Try sending a test message and watch the debug output

Cannot send messages to Kosmi

The send functionality uses the headless Chrome instance to inject messages into the Kosmi chat input field.

To debug:

1. Enable debug logging with -debug flag
2. Look for "Sending message to Kosmi" in logs
3. Check for any JavaScript errors in the browser console logs

Next Steps

• Customize message format: Edit the format strings in kosmi.go
• Add more bridges: Matterbridge supports Discord, Slack, Telegram, etc.
• Set up as a service: Use systemd or similar to run automatically
• Monitor logs: Set up log rotation and monitoring

Getting Help

• Check INTEGRATION.md for detailed integration steps
• Check README.md for architecture details
• Enable debug logging for detailed troubleshooting
• Review the chrome extension code in .examples/ for API details

Common Use Cases

Home Server Setup

# Bridge your Kosmi room with your home IRC server
[kosmi.gamenight]
RoomURL="https://app.kosmi.io/room/@gamenight"

[irc.home]
Server="irc.home.local:6667"
Nick="kosmi-relay"
UseTLS=false

[[gateway]]
name="gamenight"
enable=true

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

[[gateway.inout]]
account="irc.home"
channel="#gamenight"

Multiple Rooms

# Bridge multiple Kosmi rooms
[kosmi.room1]
RoomURL="https://app.kosmi.io/room/@room1"

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

[irc.libera]
Server="irc.libera.chat:6667"
Nick="kosmi-bot"

# Gateway for room1
[[gateway]]
name="gateway1"
enable=true

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

[[gateway.inout]]
account="irc.libera"
channel="#room1"

# Gateway for room2
[[gateway]]
name="gateway2"
enable=true

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

[[gateway.inout]]
account="irc.libera"
channel="#room2"

Success!

If you see messages flowing both ways, congratulations! Your Kosmi-IRC bridge is working. 🎉

For advanced configuration and features, see the full documentation in README.md and INTEGRATION.md.