Development

Development

RulZ LLM Suite is an Electron app written in TypeScript with a React interface. The source is on GitHub under the MIT License.

Building from source

You need Windows, Node.js 22.12 or newer (the project is developed on Node 24) and git.

git clone https://github.com/speedyrulz/rulz-llm-suite.git
cd rulz-llm-suite
npm install
node node_modules/electron/install.js   # first time only: Electron downloads its binary lazily
npm run dev                              # run with hot reload

Command	What it does
npm run dev	Start the app with hot reload
npm run build	Build the main, preload and renderer bundles into out/
npm start	Preview the built bundles
npm run typecheck	Type-check the main-process and renderer code
npm test	Run the unit tests (Vitest)
npm run build:win	Build the NSIS installer into dist/

install.bat and run.bat in the repository root wrap the common steps for people who don't use a terminal. run.bat dev starts hot reload; run.bat build rebuilds first.

You also need a llama-server.exe to run models; see Building the Engine.

How it is organised

src/main       Electron main process
  engine/        finding llama-server, starting one process per model, hardware meters, load arguments
  models/        GGUF header reader, library scan and grouping, memory estimate
  chat/          streaming chat, context fitting, chat storage
  mcp/           MCP client: connections, tool calls
  server/        the local OpenAI/Anthropic-compatible API server
  settings/      settings, per-model defaults and presets (validated on load)
src/preload    the contextBridge API exposed to the UI
src/renderer   the React UI: pages, components and zustand stores
src/shared     types, the IPC contract, defaults and helpers used on both sides
tests          unit tests
docs           screenshots used by the README and this wiki

Key design points:

• One llama-server per loaded model, each on its own localhost port with the full command line built from the model's load settings. This gives per-model settings and logs, crash detection and a clean unload.
• The UI never talks to llama-server directly. Chat streaming goes through the main process, which also does context fitting, tool-definition handling and token counting. The local API server sits in front of the same process manager.
• A typed IPC contract in src/shared/ipc.ts is the single source of truth for requests and events between the UI and the main process.
• Security defaults: context isolation and the renderer sandbox are on, Node integration is off, production builds ship a strict Content-Security-Policy, and every llama-server is bound to 127.0.0.1.
• Pure logic is kept separate and unit-tested: the GGUF reader, model grouping, load-argument builder, memory estimate, SSE parser, context fitting, MCP config parsing, tool search and compaction, and the API server's model resolution.

Tests and checks

npm run typecheck
npm test

GitHub Actions runs the type-check, the tests and a build on every push to master and on every pull request (.github/workflows/ci.yml).

Releasing

1. Update version in package.json (and the lock file) and commit.

2. Tag and push:

   git tag v0.4.0
   git push origin v0.4.0
   

3. The release workflow (.github/workflows/release.yml) type-checks, tests and builds the installer on a Windows runner, then attaches RulZ-LLM-Suite-Setup-<version>.exe to a new GitHub Release with generated notes.

To build an installer locally, run npm run build:win. If it fails on symbolic links, see Troubleshooting.

Reporting problems

Bug reports and feature requests are welcome on the issue tracker. Please include your app version, your GPUs, the model, and the relevant lines from the model's log, with any keys or tokens removed.

License and branding

The source code is released under the MIT License. The RulZ name and logo are excluded from that license and all rights are reserved; if you fork or redistribute the project, remove or replace the RulZ branding. See LOGO-NOTICE.md.