A lightweight live chat overlay that connects to a remote Streamer.bot instance over WebSocket and displays Twitch/YouTube chat messages in a clean dark-themed browser window.

1. The chat script launches an isolated Helium browser window pointed at chat.html via a file:// URL.
2. chat.html loads the bundled streamerbot-client.js library and opens a WebSocket connection to Streamer.bot.
3. Incoming Twitch.ChatMessage and YouTube.ChatMessage events are parsed and rendered in real time.

No HTTP server is involved -- the page loads directly from disk.

Python, curl, and a web server are not required.

1. Open Streamer.bot.
2. Go to Servers/Clients - WebSocket Server.
3. Enable the WebSocket server.
4. Set the bind address to your LAN IP (e.g. 10.0.0.195) -- not 127.0.0.1, otherwise remote connections will be refused.
5. Set the port to 8080 (or update chat.html to match your chosen port).
6. Make sure your Windows firewall allows inbound connections on that port.

Clone the repo:

Make the script executable:

Edit chat.html and update the host/port to match your Streamer.bot machine:

Or from anywhere:

The overlay opens as a standalone app window (no browser chrome/address bar) with:

• A dark header showing "Live Chat" and a connection status badge
  • Orange = Connecting...
  • Green = Connected
  • Red = Disconnected
• Each chat message shows:
  • Twitch or YouTube platform icon
  • User badges (broadcaster, subscriber, etc.)
  • Username in the user's chat colour
  • Message text
  • Timestamp

The window blocks the terminal until it is closed, then exits cleanly.

• CHAT_FILE -- absolute path to the HTML file, hardcoded to $HOME.
• PROFILE_DIR -- a persistent isolated Chromium profile stored in ~/.config. Keeping it persistent avoids a slow first-run initialisation on every launch.

Chromium writes a SingletonLock file to prevent two instances sharing a profile. If the browser crashes or is killed, the lock is never cleaned up, causing subsequent launches to hand the URL off to a non-existent process (resulting in a grey window). Only the lock files are removed -- the rest of the profile is preserved.

The script runs Helium in the foreground (no &), so it naturally blocks until the window is closed -- no need to track PIDs.

streamerbot-client.js is a local copy of the @streamerbot/client npm package. It is bundled locally so the overlay works without internet access.

To update it to the latest version:

Edit chat.html and update the StreamerbotClient constructor:

Run the included install script to register the overlay as an application in your launcher (rofi, dmenu, GNOME, KDE, etc.):

This will:

• Make the chat script executable
• Write a .desktop entry to ~/.local/share/applications/streamerbot-chat.desktop using the correct absolute path automatically
• Refresh the desktop database so the entry appears in your launcher immediately

You can then launch StreamerBot Chat from your application launcher like any other app, no terminal needed.

Grey/blank window on launch The SingletonLock cleanup in the script handles this automatically. If it still happens, delete the entire profile and let it rebuild:

Status stays "Connecting..." forever

• Confirm Streamer.bot is running on the Windows machine.
• Confirm the WebSocket server in Streamer.bot is enabled and bound to the LAN IP (not 127.0.0.1).
• Test connectivity from the Linux machine:
  nc -zv 10.0.0.195 8080
• Check that the Windows firewall allows inbound TCP on port 8080.

Messages appear but are blank The payload structure from Streamer.bot changed. Open chat.html, add onData: (raw) => console.log(raw) to the StreamerbotClient constructor, relaunch, and inspect the browser console (right-click - Inspect) to see the raw payload shape. Then update handleChatMessage accordingly.

"Opening in existing browser session" and nothing loads An existing Helium window is running without --user-data-dir. The SingletonLock cleanup and --user-data-dir flag together prevent this. If it recurs, kill all Helium processes:

Then relaunch with ./chat.