Repository navigation
Development
For people working on CrossChat itself.
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
| 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 |
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 LinuxBoth 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'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.
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.
- 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.
Get started
Use it
Reference
Help
Developers