From 4dc73fb36adb4b89a041c32db75f8240d67dc2c3 Mon Sep 17 00:00:00 2001 From: easypathuni Date: Fri, 18 Sep 2026 18:24:11 +0300 Subject: [PATCH] chore: add Windows helpers to run OmniRoute and Claude Code from a source checkout (#13312) * chore: add Windows helpers to run OmniRoute and Claude Code from a source checkout Adds contrib/windows/ with two double-clickable scripts for Windows users who cloned the repo instead of installing the npm package: - start-omniroute.bat -> npm run dev (resolves the repo root from its own path) - launch-claude.bat -> node bin/omniroute.mjs launch, forwarding extra args The README documents a fresh-clone gotcha on Windows with npm >= 11: the optional better-sqlite3 dependency is silently skipped, the server falls back to node:sqlite and logs "Module not found: Can't resolve 'better-sqlite3'". Since better-sqlite3@13 ships win32-x64 prebuilds inside the package, extracting the npm pack into node_modules fixes it without a compiler. Verified on Windows 11, Node 24.14.0, npm 11.6.1. * chore(contrib): start Claude Code in the project folder, not the OmniRoute checkout launch-claude.bat used to cd into the repo root before exec'ing `omniroute launch`, so Claude Code always started inside the OmniRoute checkout and loaded this repo's CLAUDE.md/AGENTS.md (~60k chars) into the user's own coding session. Take the project folder as the first argument (or prompt for it on double-click) and resolve bin/omniroute.mjs from the script's own path instead. Remaining args are still forwarded to `omniroute launch`. --- contrib/windows/README.md | 45 +++++++++++++++++++++++++++++ contrib/windows/launch-claude.bat | 33 +++++++++++++++++++++ contrib/windows/start-omniroute.bat | 11 +++++++ 3 files changed, 89 insertions(+) create mode 100644 contrib/windows/README.md create mode 100644 contrib/windows/launch-claude.bat create mode 100644 contrib/windows/start-omniroute.bat diff --git a/contrib/windows/README.md b/contrib/windows/README.md new file mode 100644 index 0000000000..8349cfb94b --- /dev/null +++ b/contrib/windows/README.md @@ -0,0 +1,45 @@ +# Windows helpers — run OmniRoute from a source checkout + +Two double-clickable `.bat` files for Windows users who cloned the repo instead of +installing the npm package. Both resolve the repo root from their own location, so they +work from any checkout path. + +| File | What it does | +| --------------------- | ---------------------------------------------------------------------------------- | +| `start-omniroute.bat` | `npm run dev` — dev server + dashboard on `http://localhost:20128` | +| `launch-claude.bat` | `node bin\omniroute.mjs launch` — opens Claude Code pointed at the local OmniRoute | + +Usage: + +1. `npm install` once (see the note below if you are on npm ≥ 11). +2. Double-click `start-omniroute.bat` and wait for `dev server listening on http://0.0.0.0:20128`. +3. Open the dashboard, connect a provider, copy an API key from **Endpoints**. +4. Double-click `launch-claude.bat`. Extra arguments are forwarded, e.g. + `launch-claude.bat --profile glm52` after `node bin\omniroute.mjs setup-claude`. + +## npm ≥ 11 skips `better-sqlite3` on Windows + +`better-sqlite3` is an `optionalDependency`. npm 11 blocks install scripts of optional +dependencies by default, so on a fresh clone `node_modules/better-sqlite3/` may simply not +exist. The server still boots (it falls back to `node:sqlite`, which Node marks +experimental), but `npm run dev` logs `Module not found: Can't resolve 'better-sqlite3'` +and `[DB] Driver: node:sqlite`. + +Since `better-sqlite3@13` ships prebuilt binaries inside the package +(`prebuilds/win32-x64.node`), no compiler is needed — just put the package in place: + +```powershell +cd node_modules +npm pack better-sqlite3@13.0.3 +tar -xzf better-sqlite3-13.0.3.tgz +Remove-Item -Recurse -Force better-sqlite3 -ErrorAction SilentlyContinue +Rename-Item package better-sqlite3 +Remove-Item better-sqlite3-13.0.3.tgz +``` + +Restart the server; the log should now read `[DB] Driver: better-sqlite3`. + +> If you do need to compile a native addon and `python` resolves to the Microsoft Store +> build, `node-gyp` fails with `common.gypi not found` even after downloading headers — the +> Store Python sandboxes `%LOCALAPPDATA%`. Pass `--devdir` pointing outside `AppData\Local` +> (or install python.org Python). diff --git a/contrib/windows/launch-claude.bat b/contrib/windows/launch-claude.bat new file mode 100644 index 0000000000..d4fd6d9dc8 --- /dev/null +++ b/contrib/windows/launch-claude.bat @@ -0,0 +1,33 @@ +@echo off +rem OmniRoute — launch Claude Code pointed at the local OmniRoute server (Windows). +rem Wraps `omniroute launch` from the source checkout so no global install is needed. +rem +rem Usage: launch-claude.bat [project-folder] [omniroute launch args...] +rem - From a terminal inside your project: launch-claude.bat (opens here) +rem - Double-click: prompts for the project folder (Enter = current folder) +rem Claude Code is started in the PROJECT folder, never in the OmniRoute checkout — +rem otherwise it loads this repo's CLAUDE.md/AGENTS.md (~60k chars) into every session. +setlocal enabledelayedexpansion +title Claude Code via OmniRoute +set "OMNIROUTE_ROOT=%~dp0..\.." + +if exist "%~1\" ( + cd /d "%~1" + shift +) else ( + set "PROJ=" + set /p "PROJ=Project folder (Enter = current: %CD%): " + if not "!PROJ!"=="" cd /d "!PROJ!" +) + +set "ARGS=" +:collect +if "%~1"=="" goto run +set "ARGS=!ARGS! %1" +shift +goto collect + +:run +node "%OMNIROUTE_ROOT%\bin\omniroute.mjs" launch!ARGS! +endlocal +pause diff --git a/contrib/windows/start-omniroute.bat b/contrib/windows/start-omniroute.bat new file mode 100644 index 0000000000..f1a8aa78ae --- /dev/null +++ b/contrib/windows/start-omniroute.bat @@ -0,0 +1,11 @@ +@echo off +rem OmniRoute — start the dev server from a source checkout (Windows). +rem Double-click, or run from any directory. Resolves the repo root from this file's location. +setlocal +title OmniRoute Server +cd /d "%~dp0..\.." +echo Starting OmniRoute on http://localhost:20128 ... +echo (Leave this window open. Close it to stop the server.) +call npm run dev +endlocal +pause