c88b75f30d
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>
205 lines
5.2 KiB
Markdown
205 lines
5.2 KiB
Markdown
# Quick Reference Guide
|
|
|
|
## Running the Bridge
|
|
|
|
### Build and Run Locally
|
|
|
|
```bash
|
|
cd /Users/erikfredericks/dev-ai/HSO/irc-kosmi-relay
|
|
go build -o matterbridge .
|
|
./matterbridge -conf matterbridge.toml
|
|
```
|
|
|
|
### Run with Docker
|
|
|
|
```bash
|
|
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](../IRC.md) for full details including vote syntax and ticker symbols.
|
|
|
|
## Configuration
|
|
|
|
### Minimal Configuration
|
|
|
|
```toml
|
|
[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
|
|
|
|
```toml
|
|
[kosmi.myroom]
|
|
RoomURL="https://app.kosmi.io/room/@yourroom"
|
|
Email="your-email@example.com"
|
|
Password="your-password"
|
|
```
|
|
|
|
### With Jackbox Integration
|
|
|
|
```toml
|
|
[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
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
# Local
|
|
kill -SIGUSR1 $(pgrep matterbridge)
|
|
|
|
# Docker
|
|
docker kill -s SIGUSR1 kosmi-irc-relay
|
|
```
|
|
|
|
## Docker Commands
|
|
|
|
```bash
|
|
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](../../README.md) -- Project overview and architecture
|
|
- [IRC.md](../IRC.md) -- IRC command and voting reference
|
|
- [DOCKER_QUICKSTART.md](DOCKER_QUICKSTART.md) -- 5-minute Docker setup
|
|
- [JACKBOX_INTEGRATION.md](JACKBOX_INTEGRATION.md) -- Jackbox Game Picker setup
|
|
- [BROWSER_AUTH_GUIDE.md](BROWSER_AUTH_GUIDE.md) -- Email/password authentication
|
|
- [MUTE_CONTROL.md](MUTE_CONTROL.md) -- Mute toggle guide
|