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

# 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