Skip to content

Development

Randy Northrup edited this page Nov 9, 2026 · 2 revisions

Development

For people working on CrossChat itself.

How it fits together

flowchart LR
  APP["Streaming app"] -- "stream started / stopped" --> HUB
  subgraph PC["Your PC (127.0.0.1 only)"]
    HUB["CrossChat hub<br/>hub/hub.py"]
    WIN["Chat window"]
    WID["Widgets<br/>chat · featured · viewers · alerts"]
    EXT["Browser extension"]
  end
  CHAT["Twitch, YouTube, Kick,<br/>Rumble chat"] --> HUB
  PH["Phone or other PC<br/>(paired, port 4467)"] <--> HUB
  HUB -- live feed --> WIN
  HUB -- live feed --> WID
  WIN -- "replies, moderation" --> EXT
  EXT -- "posts as you" --> SITES["YouTube, X, TikTok,<br/>Facebook, Instagram, Rumble"]
  PAGES["X, TikTok, Facebook,<br/>Instagram live pages"] -- "chat they show" --> EXT --> HUB
Loading
Part Path Does
The hub hub/hub.py A small Python program. Reads each platform's chat, follows the streaming app, and serves everything on 127.0.0.1
The web pages hub/web/ The chat window, Theme Studio and widgets
The OBS script obs/crosschat.lua Starts the hub with OBS, and adds buttons and hotkeys
The extension extension/ Does what only your signed-in browser can do

Run and test it

python -m pip install -r hub/requirements.txt pytest ruff
python hub/hub.py --test --twitch <any live channel>     # the hub without OBS, against real chat
python hub/hub.py --demo                                 # a made-up live stream
ruff check hub scripts tests
python -m pytest
node --test "tests/js/*.test.mjs"

pip install lupa (on a Mac: brew install luajit) adds the OBS script tests.

Against a real browser or OBS:

python scripts/obs_e2e.py --obs <portable OBS folder>    # end to end with a real OBS
python3 scripts/window_e2e.py                            # CrossChat's windows, on macOS and Linux

Both use throwaway profiles and never touch your own OBS or browser. The checks workflow runs them on every change.

On Linux, tests that keep a secret need a desktop keyring and are skipped where none answers. To give them one of their own:

dbus-run-session -- bash -c 'printf test | gnome-keyring-daemon --unlock --components=secrets >/dev/null; python -m pytest'

Build the downloads

pwsh scripts/package.ps1          # dist\CrossChat-<version>-windows.zip
pwsh installer/build.ps1          # dist\CrossChat-Setup-<version>.exe (Windows only)
python scripts/package_mac.py     # dist/CrossChat-<version>-mac.zip (any system)
python scripts/package_linux.py   # dist/CrossChat-<version>-linux.tar.gz (any system)

The hub, the extension's manifest and the OBS script must all carry the same version, or the build stops.

Releases

Pushing a v* tag runs the release workflow. It tests on Windows, Mac and Linux, builds from a fresh checkout, signs the setup program, attests the downloads and publishes them. Its notes come from that version's section in CHANGELOG.md, so write that first.

See the README's code signing policy.

Contributing

  • Report bugs and ideas in Issues.
  • Report security problems privately.
  • Viewers' words go onto pages as text only (textContent), never as HTML.
  • Anything that does something must be refused when another website asks for it. See SECURITY.md.

Clone this wiki locally