TomyJan/SnowLuma

What it does

SnowLuma is a TypeScript interoperability runtime that turns native QQ client sessions into OneBot v11 actions and events. It exposes those events to applications through WebSocket server/client and HTTP server/report endpoints, plus a WebUI, a TypeScript SDK and an MCP package. It is aimed at bot developers who already work with QQ and want a standardized protocol layer rather than integrating one-off client callbacks.

The runtime keeps session access, protocol parsing, identity mapping, OneBot conversion and network adaptation as separate boundaries, so several QQ accounts can run in parallel with their own sessions, identity mappings, message storage and network settings. Message support covers text, images, voice, video, files, replies, mentions, forwards and common card formats. A WebUI provides account status, live logs, connection configuration, action debugging and storage management.

Quick start

1. Download the full release package for your platform from SnowLuma Releases and extract it. The Lite build requires Node.js 24 or newer.

2. On Windows, run launcher.bat. On Linux, make the script executable and run it:

   chmod +x launcher.sh
   ./launcher.sh
   

3. Open the local WebUI at http://localhost:5099, log in with the initial password printed in the startup log, then follow the setup flow to connect the QQ process and configure your OneBot connections.

Account detection relies on login-database file changes, process/login events or manual action rather than periodic polling; if a process is not picked up, refresh or reconnect from the process row in the WebUI. For Docker and Windows deployment options, see the deployment guide; the OneBot action surface is documented in the API reference.

Usage constraints

SnowLuma is an independent third-party project with no affiliation or authorization from Tencent or QQ; it is presented for study and technical research, and users are responsible for complying with the QQ user agreement and applicable law. The license is source-available but not OSI open source: viewing, learning, non-commercial self-hosting and private modification are allowed, while commercial use and public distribution of modified or derivative versions need prior written permission. See the license and the EULA. The bundled native add-ons are proprietary and outside the source license. Release packages target Windows x64 and Linux x64/arm64.

Development

Development uses Node.js 24+ and pnpm 11.25.0 on the dev branch. The repository documents the clone, install, typecheck and test flow, plus contribution and module-boundary notes in CONTRIBUTING.md and CONTEXT.md. SDK and MCP integration details live in their package READMEs: SDK and MCP.

HotRepo's take

SnowLuma entered HotRepo's new-project list on 2026-11-10 with the TypeScript list and a same-window count of 109 stars and 285 forks gained. The fork count being well above the star count is notable for a protocol-bridge runtime, but one snapshot cannot establish a trend or explain why; the repository's Github record has no all-language daily rank entry yet, so its standing on the broader daily chart is unknown.