HyperSpaceOut/IRC-kosmi-relay
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: comprehensive documentation overhaul

Browse Source 
Rewrite README.md and all setup guides to reflect the current native
GraphQL WebSocket architecture (replacing stale headless Chrome/WebSocket
interception descriptions). Add new docs/IRC.md with complete IRC command
reference, vote syntax, and ticker symbol table.

Archive pre-edit docs to docs/archive/setup-backup-2026-05-10/ and move
historical development notes from docs/ root into docs/archive/.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cottongin
2026-05-12 22:01:25 -04:00
parent 4188ae29af
commit c88b75f30d
57 changed files with 4530 additions and 1994 deletions
Download Patch File Download Diff File Expand all files Collapse all files

319
docs/setup/QUICKSTART.md
View File

@@ -1,301 +1,130 @@
# Quick Start Guide
Get the Kosmi-IRC bridge running in minutes!
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
- Go 1.23 or higher
- Chrome/Chromium (only needed for email/password authentication)
- A Kosmi room URL
- (Optional) IRC server access for full relay
## Step 1: Test Kosmi Connection
First, verify the bridge can connect to Kosmi:
## Step 1: Build the Bridge
```bash
# Build the test program
go build -o test-kosmi ./cmd/test-kosmi
cd irc-kosmi-relay
# 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:
```bash
# 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
# Download dependencies
go mod download
# Build
go build
go build -o matterbridge .
```
### Option B: Use This Repository
## Step 2: Configure
This repository has a minimal Matterbridge structure. To add IRC support:
Copy and edit the example configuration:
1. Copy IRC bridge from Matterbridge:
```bash
# 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/
```
```bash
cp matterbridge.toml.example matterbridge.toml
nano matterbridge.toml
```
2. Update dependencies:
```bash
cd /path/to/irc-kosmi-relay
go mod tidy
```
## Step 3: Configure
Edit `matterbridge.toml`:
Update these values:
```toml
# Kosmi configuration
[kosmi.hyperspaceout]
RoomURL="https://app.kosmi.io/room/@hyperspaceout"
RoomURL="https://app.kosmi.io/room/@YOUR_ROOM"
# 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
[irc.zeronode]
Server="irc.libera.chat:6697"
Nick="your-bot-nick"
UseTLS=true
[[gateway.inout]]
account="kosmi.hyperspaceout"
channel="main"
[[gateway.inout]]
account="irc.libera"
account="irc.zeronode"
channel="#your-channel"
```
**Important**: Replace:
- `https://app.kosmi.io/room/@hyperspaceout` with your Kosmi room URL
- `#your-channel` with your IRC channel
**Important**: The Kosmi channel is always `"main"` (one channel per room). The IRC channel must include `#`.
## Step 4: Run
### Optional: Authenticated Kosmi Access
To use a Kosmi account instead of anonymous access, add credentials:
```toml
[kosmi.hyperspaceout]
RoomURL="https://app.kosmi.io/room/@YOUR_ROOM"
Email="your-email@example.com"
Password="your-password"
```
This requires Chrome/Chromium for the initial browser-based login. The JWT is cached locally for subsequent runs.
## Step 3: Run
```bash
./matterbridge -conf matterbridge.toml
```
Or with debug logging:
```bash
./matterbridge -conf matterbridge.toml -debug
```
## Step 5: Test the Relay
### Expected Output (Success)
1. **Kosmi → IRC**: Send a message in Kosmi. It should appear in IRC as:
```
INFO Running version ...
INFO Connecting to Kosmi
INFO Extracted room ID: @YOUR_ROOM
INFO No credentials provided, using anonymous access
INFO Successfully connected to Kosmi
INFO Connection succeeded (IRC)
INFO Gateway(s) started successfully. Now relaying messages
```
## Step 4: Test the Relay
1. **Kosmi --> IRC**: Send a message in your Kosmi room. It should appear in IRC as:
```
[Kosmi] <username> your message here
[kosmi] <username> your message here
```
2. **IRC → Kosmi**: Send a message in IRC. It should appear in Kosmi as:
2. **IRC --> Kosmi**: Send a message in your IRC channel. It should appear in Kosmi as:
```
[IRC] <username> your message here
[irc] <username> your message here
```
## Troubleshooting
### Test program doesn't connect
### Kosmi connection fails
**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
- Verify the room URL is correct (use the full URL from your browser)
- Check network connectivity: `curl -I https://app.kosmi.io`
- Run with `-debug` for detailed WebSocket connection logs
**Solution**:
```bash
# Test Chrome installation
which google-chrome chromium chromium-browser
**Supported room URL formats:**
- `https://app.kosmi.io/room/@roomname`
- `https://app.kosmi.io/room/roomid`
# Test network connectivity
curl -I https://app.kosmi.io
### Authentication issues
# Run with debug
./test-kosmi -room "YOUR_ROOM_URL" -debug
```
- Verify Chrome/Chromium is installed: `which chromium chromium-browser google-chrome`
- Check credentials are correct by logging in manually at `app.kosmi.io`
- Delete the token cache to force a fresh login: `rm -f data/kosmi_token_cache.json`
- See [BROWSER_AUTH_GUIDE.md](BROWSER_AUTH_GUIDE.md) for detailed auth troubleshooting
### 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**:
```bash
# 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
- Confirm both bridges are connected (look for success messages in logs)
- Verify channel names match in the gateway configuration
- Enable debug logging to trace message flow
## 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
```toml
# 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
```toml
# 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`.
- [DOCKER_QUICKSTART.md](DOCKER_QUICKSTART.md) -- Deploy with Docker
- [JACKBOX_INTEGRATION.md](JACKBOX_INTEGRATION.md) -- Enable Jackbox Game Picker
- [IRC.md](../IRC.md) -- IRC commands and voting reference
- [MUTE_CONTROL.md](MUTE_CONTROL.md) -- Control Jackbox announcement muting