@prakashpro1/auto-modal 1.0.0

package/.env.example

@@ -0,0 +1,10 @@
+# Copy to .env and fill in your keys.
+# Add as MANY keys as you have, comma-separated — the router rotates through all
+# of them when one hits its rate/usage limit. No limit on how many you list.
+# Scale by editing this file only; you never need to touch config.yaml.
+
+# OpenRouter keys: https://openrouter.ai/keys
+OPENROUTER_API_KEYS=sk-or-v1-aaa...,sk-or-v1-bbb...,sk-or-v1-ccc...
+
+# HuggingFace tokens (read scope): https://huggingface.co/settings/tokens
+HF_API_KEYS=hf_aaa...,hf_bbb...

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 godlikebgis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,282 @@
+# Auto Modal
+
+![Dashboard](dashboard.png)
+
+A local proxy that **automatically switches models AND API keys when a usage/rate
+limit is exceeded**. Each model has a pool of keys; when a model+key returns `429`
+(rate limit) or `402` (out of credits), the router cools that slot down and rotates
+to the next **key**, then the next **model** — transparently, in the same request.
+It only fails once *every key of every model* is spent.
+
+It speaks **both** API dialects from one endpoint:
+
+| Client | API it expects | Router endpoint |
+|---|---|---|
+| **Continue**, OpenAI SDKs, curl | OpenAI | `/v1/chat/completions`, `/v1/completions` |
+| **Claude Code CLI** | Anthropic | `/v1/messages` (translated ⇄ OpenAI) |
+
+```
+client ──► router ──►  nemotron-free (OpenRouter)  key0 →429→ key1 →429→ ┐
+                       owl-alpha     (OpenRouter)  key0 →429→ key1 →429→ ┤ rotate key,
+                       qwen-72b      (HuggingFace) key0 ✅              ◄┘ then model
+```
+
+---
+
+## Features
+
+- **Model + key rotation** on `429` / `402` / network errors — each model holds a
+  key pool; a limited key is skipped and the next (even a different account) is tried.
+- **Per-day caps** — counts requests per `(model, key)` (persisted to `usage.json`)
+  and proactively skips a slot at its `dailyLimit`.
+- **Per-minute rate limit** — a token bucket per slot (`rpm`) rotates *before* the
+  upstream returns `429`, smoothing load.
+- **Cooldown** — a slot that just hit a limit is skipped for `cooldownMs`.
+- **Transient retries** — `5xx` / timeouts retry the same slot before rotating.
+- **Streaming** (SSE) and non-streaming, on every endpoint.
+- **Two API dialects** — OpenAI (Continue) and Anthropic (Claude Code), same routing.
+- **Live dashboard** — add/test/edit/reorder/delete models, add/remove keys, watch
+  per-slot usage, sparklines, and the real OpenRouter free-pool — all hot-reloaded.
+
+---
+
+## Install as a CLI
+
+**Global** (one `automodal` command everywhere):
+```bash
+npm install -g @prakashpro1/auto-modal     # → `automodal` on your PATH
+automodal init                # creates ~/.auto-modal/{config.yaml,.env}
+# add your keys to ~/.auto-modal/.env  (or use the dashboard 🔑 panel)
+automodal                     # start the router → http://localhost:8787
+```
+
+**Per-project** (scoped to one repo, run via `npx`):
+```bash
+cd your-project
+npm install @prakashpro1/auto-modal              # add as a dependency
+npx automodal init --local          # creates ./.auto-modal/ for THIS project
+npx automodal                       # start it
+```
+Add `.auto-modal/` to the project's `.gitignore` — it holds your keys.
+
+Commands (run from anywhere):
+| Command | Does |
+|---|---|
+| `automodal` / `automodal start` | start the router (auto-kills any stale instance first) |
+| `automodal claude [args]` | launch Claude Code through the router |
+| `automodal init [--local]` | create global `~/.auto-modal` (or project `./.auto-modal`) |
+| `automodal where` | print which config / `.env` / `usage.json` is in effect |
+| `automodal --help` | usage |
+
+**Config resolution** (highest priority first):
+`AUTOMODAL_HOME` env  →  nearest `./.auto-modal` (walking up from cwd)  →  `~/.auto-modal`.
+
+So a project with its own `./.auto-modal/` uses that (its own chain + keys); anywhere
+else falls back to the global `~/.auto-modal/`. The CLI never writes inside the package.
+
+## Setup (from source / dev)
+
+```bash
+cd <path-to-automodal>
+npm install
+cp .env.example .env          # add your keys (comma-separated for multiple)
+npm start                     # → http://localhost:8787
+```
+
+`.env`:
+```bash
+OPENROUTER_API_KEYS=sk-or-1...,sk-or-2...   # as many as you have; rotated automatically
+HF_API_KEYS=hf_1...,hf_2...
+```
+
+Verify: `curl -s http://localhost:8787/health` → `{"ok":true,"models":N}`.
+Open the dashboard at <http://localhost:8787/> to manage everything visually.
+
+> `npm start` self-guards: a `prestart` hook kills any stale instance already on
+> the port first, so you never end up with two routers fighting over state. Use
+> `npm run restart` to force a clean restart.
+
+---
+
+## Use it with Continue (VS Code)
+
+Add to `~/.continue/config.yaml`:
+```yaml
+models:
+  - name: Pro Model
+    provider: openai
+    model: auto                 # router picks the model (chain + rotation)
+    apiBase: http://localhost:8787/v1
+    apiKey: dummy               # router holds the real keys
+    roles: [chat, edit, apply, autocomplete]
+```
+- Skip `embed` / `rerank` — the router proxies completions only; use separate models.
+- **Autocomplete** uses `/v1/completions`, routed the same way.
+- **Images:** point a dedicated entry at a vision model with `capabilities: [image_input]`
+  (free text models can't accept images). Route it through the router with
+  `model: <vision-chain-id>` to keep key rotation.
+
+---
+
+## Use it with Claude Code CLI
+
+Claude Code speaks the **Anthropic Messages API**; the router exposes `POST /v1/messages`
+(+ `/v1/messages/count_tokens`) and translates request/response/streaming-SSE and tool
+calls ⇄ OpenAI, then routes through the same chain.
+
+**Prerequisites:** router installed (`npm install`), keys in `.env`, and the `claude`
+CLI installed.
+
+### Step 1 — Start the router (Terminal A)
+```bash
+cd <path-to-automodal>
+npm start
+curl -s http://localhost:8787/health     # → {"ok":true,"models":N}
+```
+
+### Step 2 — Launch Claude Code through the router (Terminal B)
+If you installed the global CLI, just run from anywhere:
+```bash
+automodal claude                          # interactive
+automodal claude -p "explain this repo"   # headless / one-shot
+```
+From source (no global install), use the bundled launcher:
+```bash
+cd <path-to-automodal>
+./claude-router.sh                        # interactive
+./claude-router.sh -p "explain this repo" # headless / one-shot
+```
+The launcher checks the router is up, then sets these **for that invocation only**
+(your normal `claude` stays on real Anthropic):
+```bash
+ANTHROPIC_BASE_URL=http://localhost:8787
+ANTHROPIC_AUTH_TOKEN=dummy        # router holds the real provider keys
+ANTHROPIC_MODEL=auto              # full chain + rotation
+ANTHROPIC_SMALL_FAST_MODEL=auto
+```
+Prefer manual env vars instead of the script? Export the four above and run `claude`.
+
+### Step 3 (optional) — Pick a model
+- **Auto chain** (default): `ANTHROPIC_MODEL=auto` — rotates models + keys.
+- **Pin one**: `ANTHROPIC_MODEL=claude-owl-alpha ./claude-router.sh` — the router
+  strips the `claude-` prefix to match a chain id.
+- **Switch in-session**: `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 ./claude-router.sh`,
+  then type `/model` and pick a `claude-<id>` entry (advertised via `GET /v1/models`).
+
+### Step 4 — Watch it work
+Open <http://localhost:8787/> while you use Claude Code — requests land on slots,
+sparklines grow, daily/free-pool counters tick.
+
+### Sanity test
+```bash
+./claude-router.sh -p "What is 2+2? Reply with just the number."   # → 4
+```
+
+### Troubleshooting
+| Symptom | Fix |
+|---|---|
+| `✗ Router not reachable` | Start the router (Step 1). |
+| `overloaded_error` / 529 | All slots exhausted (e.g. free daily pool spent) — add a key in the 🔑 dashboard, or wait for 00:00 UTC. |
+| Flaky tool calls / odd multi-step | Expected on free models — pin a tool-capable one (`claude-owl-alpha`). |
+
+> ⚠️ Claude Code is tuned for Claude models (heavy agentic tool use, big context).
+> Free OpenRouter/HF models connect and respond but are far weaker at tool calling
+> and long agent loops — a "make it work" path, not Claude parity.
+
+---
+
+## Dashboard (`GET /`)
+
+Auto-refreshes every 2s. One card per model, a row per key-slot.
+
+- **Add a model** — searchable picker pulling each provider's live catalog
+  (filter to free, sorted by context); ID + key-env auto-filled. Active free
+  OpenRouter models auto-set `dailyLimit` from your account tier.
+- **🔑 API keys** — list (masked) / add / remove keys; writes `.env`, hot-reloads,
+  activates key-less models instantly.
+- **Drag-to-reorder** priority · **Test** / **Test all** (real ping, ok/latency) ·
+  **Edit** `rpm`/`dailyLimit` inline · **Delete**.
+- **Per-slot sparkline** (last 30 min) + **"Today: N of T left"** per model.
+- **OpenRouter free pool** header — the real shared cap (50/day free tier, 1000/day
+  once ≥10 credits bought) summed across all `:free` models.
+
+All edits write `config.yaml` / `.env` and hot-reload — no restart. (Dashboard edits
+normalize `config.yaml` and drop inline comments.)
+
+---
+
+## API endpoints
+
+| Endpoint | Purpose |
+|---|---|
+| `POST /v1/chat/completions` | OpenAI chat (Continue chat/edit/apply) |
+| `POST /v1/completions` | OpenAI text/FIM (Continue autocomplete) |
+| `POST /v1/messages` | Anthropic Messages (Claude Code), translated |
+| `POST /v1/messages/count_tokens` | Token estimate for Claude Code |
+| `GET /v1/models` | Chain as model list (+ `claude-<id>` aliases) |
+| `GET /` | Live dashboard |
+| `GET /status` | Chain + live usage (powers the dashboard) |
+| `GET /usage` | Raw per-slot counts + cooldown |
+| `GET /health` | Liveness + model count |
+| `GET /admin/credits` | OpenRouter tier + credit usage + derived free cap |
+| `GET /admin/catalog?provider=` | Live provider model catalog (picker) |
+| `POST/PATCH/DELETE /admin/models[...]` | Add / edit / delete / reorder / test models |
+| `GET/POST/DELETE /admin/keys` | Manage key pools |
+
+Response headers: `X-Router-Model`, `X-Router-Key`, `X-Router-Upstream` reveal which
+slot answered. Slots in `/usage` are labelled `modelId#keyIndex`.
+
+---
+
+## How "limit exceeded" is detected
+
+| Upstream status | Action |
+|---|---|
+| `429`, `402` | cool down this `(model, key)` → **rotate key, then model** |
+| `500/502/503/504` | retry same slot (`transientRetries`), then rotate |
+| `404` | endpoint unsupported by this slot → rotate (don't fail) |
+| other `4xx` | return to client (won't be fixed by switching) |
+| `2xx` | success → record usage for that `(model, key)` |
+
+---
+
+## Configuration (`config.yaml`)
+
+```yaml
+port: 8787
+cooldownMs: 3600000        # how long a limited slot rests
+transientRetries: 2        # retries on 5xx/timeout before rotating
+chain:                     # order = priority
+  - id: nemotron-super-free
+    provider: openrouter   # "openrouter" | "huggingface"
+    model: nvidia/nemotron-3-super-120b-a12b:free
+    apiKeys: ${OPENROUTER_API_KEYS}   # one env var, comma-separated, rotated
+    dailyLimit: 50         # per key (optional)
+    rpm: 20                # per-key requests/min token bucket (optional)
+```
+
+**Requesting a specific model:** if a request's `model` matches a chain **id** or
+**slug** (or `claude-<id>`), it routes to just that model (keeping key rotation);
+`auto`/unknown uses the full chain.
+
+**Env overrides:** `ROUTER_CONFIG`, `ROUTER_ENV`, `ROUTER_USAGE` relocate
+`config.yaml` / `.env` / `usage.json`.
+
+---
+
+## Notes
+
+- Daily counters roll over at **UTC midnight**.
+- OpenRouter free limit is **per key, shared across all `:free` models** — the
+  dashboard's free-pool line reflects this real cap; per-model `dailyLimit` is what
+  the router itself enforces to rotate early.
+- Token buckets and request history are in-memory (reset on restart); daily counts
+  and cooldowns persist in `usage.json`.
+
+## Development
+
+```bash
+npm test     # 10 integration test suites (routing, rotation, rpm, limits,
+             # completions, admin/keys/reorder/edit, history, Anthropic /v1/messages)
+npm run dev  # auto-restart on change
+```

package/bin/cli.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+// Global CLI for Auto Modal (the auto model router).
+//   automodal [start]        start the router (default)
+//   automodal claude [...]   launch Claude Code through the router
+//   automodal init           create ~/.auto-modal and show where to add keys
+//   automodal where          print the config/.env/usage paths
+//   automodal --help
+//
+// Config, keys and usage live in ~/.auto-modal (override with AUTOMODAL_HOME), so
+// a global install never writes inside the package dir.
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { existsSync, mkdirSync, copyFileSync, writeFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG = join(__dirname, "..");
+const HOME_ENV = process.env.AUTOMODAL_HOME;
+const GLOBAL_HOME = HOME_ENV || join(homedir(), ".auto-modal");
+const URL = process.env.ROUTER_URL || "http://localhost:8787";
+
+// Walk up from `cwd` looking for a project-local `.auto-modal/` dir.
+function findProjectHome(startDir) {
+  let dir = startDir;
+  for (;;) {
+    const candidate = join(dir, ".auto-modal");
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) return null; // hit filesystem root
+    dir = parent;
+  }
+}
+
+// Config home resolution (highest priority first):
+//   1. AUTOMODAL_HOME env var
+//   2. a project-local ./.auto-modal found by walking up from cwd  (per-project)
+//   3. ~/.auto-modal                                               (global)
+function resolveHome() {
+  if (HOME_ENV) return { home: HOME_ENV, scope: "env" };
+  const proj = findProjectHome(process.cwd());
+  if (proj) return { home: proj, scope: "project" };
+  return { home: GLOBAL_HOME, scope: "global" };
+}
+
+function ensureHome(home) {
+  if (!existsSync(home)) mkdirSync(home, { recursive: true });
+  const cfg = join(home, "config.yaml");
+  if (!existsSync(cfg)) {
+    // Ship config.default.yaml; fall back to config.yaml when running from source.
+    const tmpl = existsSync(join(PKG, "config.default.yaml"))
+      ? join(PKG, "config.default.yaml") : join(PKG, "config.yaml");
+    copyFileSync(tmpl, cfg);
+  }
+  const env = join(home, ".env");
+  if (!existsSync(env)) {
+    const example = join(PKG, ".env.example");
+    if (existsSync(example)) copyFileSync(example, env);
+    else writeFileSync(env, "OPENROUTER_API_KEYS=\nHF_API_KEYS=\n");
+  }
+  // Point the server modules at this home (unless already overridden).
+  process.env.ROUTER_CONFIG ||= cfg;
+  process.env.ROUTER_ENV ||= env;
+  process.env.ROUTER_USAGE ||= join(home, "usage.json");
+  return { cfg, env };
+}
+
+const [cmd, ...rest] = process.argv.slice(2);
+
+if (cmd === "--help" || cmd === "-h" || cmd === "help") {
+  console.log(`auto-modal — auto model router (key/model switching proxy)
+
+Usage:
+  automodal [start]        Start the router         (default; http://localhost:8787)
+  automodal claude [args]  Launch Claude Code through the router
+  automodal init           Create global config (~/.auto-modal) + show where to add keys
+  automodal init --local   Create project-local config (./.auto-modal) for this project
+  automodal where          Print which config / .env / usage is in effect
+  automodal --help
+
+Config resolution (highest first):  AUTOMODAL_HOME env  >  nearest ./.auto-modal  >  ~/.auto-modal
+Install:  npm install -g auto-modal   (global)   |   npm install auto-modal + npx automodal   (per-project)`);
+  process.exit(0);
+}
+
+if (cmd === "init") {
+  const local = rest.includes("--local") || rest.includes("--project");
+  const home = local ? join(process.cwd(), ".auto-modal") : GLOBAL_HOME;
+  const { cfg, env } = ensureHome(home);
+  console.log(`Initialized ${local ? "project-local" : "global"} config at ${home}`);
+  console.log(`  config: ${cfg}`);
+  console.log(`  keys:   ${env}   ← add OPENROUTER_API_KEYS / HF_API_KEYS here`);
+  if (local) console.log(`  tip: add ".auto-modal/" to .gitignore (it holds your keys)`);
+  console.log(`Then run:  automodal`);
+  process.exit(0);
+}
+
+const { home, scope } = resolveHome();
+const { cfg, env } = ensureHome(home);
+
+if (cmd === "where") {
+  console.log(`scope:  ${scope}  (${home})`);
+  console.log(`config: ${process.env.ROUTER_CONFIG}`);
+  console.log(`env:    ${process.env.ROUTER_ENV}`);
+  console.log(`usage:  ${process.env.ROUTER_USAGE}`);
+  process.exit(0);
+}
+
+if (cmd === "claude") {
+  // Launch Claude Code pointed at the router (router must be running).
+  try {
+    const r = await fetch(`${URL}/health`);
+    if (!r.ok) throw new Error("bad status");
+  } catch {
+    console.error(`✗ Router not reachable at ${URL} — start it first:  automodal start`);
+    process.exit(1);
+  }
+  console.log(`→ Claude Code via Auto Modal (${URL})`);
+  const child = spawn("claude", rest, {
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      ANTHROPIC_BASE_URL: URL,
+      ANTHROPIC_AUTH_TOKEN: "dummy",
+      ANTHROPIC_MODEL: process.env.ANTHROPIC_MODEL || "auto",
+      ANTHROPIC_SMALL_FAST_MODEL: process.env.ANTHROPIC_SMALL_FAST_MODEL || "auto",
+    },
+  });
+  child.on("exit", (code) => process.exit(code ?? 0));
+} else if (!cmd || cmd === "start") {
+  // Free a stale instance on the port, then start the server.
+  console.log(`config: ${scope} (${home})`);
+  await import(join(PKG, "scripts", "free-port.mjs"));
+  await import(join(PKG, "src", "server.js"));
+} else {
+  console.error(`Unknown command: ${cmd}\nTry:  automodal --help`);
+  process.exit(1);
+}

package/claude-router.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Launch Claude Code against the Auto Modal instead of the real Anthropic API.
+# Env vars are set for THIS invocation only — your normal `claude` is unaffected.
+#
+# Usage:  ./claude-router.sh            (interactive)
+#         ./claude-router.sh -p "..."   (headless, args pass through)
+#
+# The router must be running first:  npm start   (http://localhost:8787)
+
+ROUTER_URL="${ROUTER_URL:-http://localhost:8787}"
+
+# Fail early with a clear message if the router isn't up.
+if ! curl -s -o /dev/null "${ROUTER_URL}/health"; then
+  echo "✗ Router not reachable at ${ROUTER_URL} — start it with: npm start" >&2
+  exit 1
+fi
+
+# ANTHROPIC_AUTH_TOKEN -> sets 'Authorization: Bearer' (the router ignores it; it
+# holds the real provider keys). Pin a specific chain model with ANTHROPIC_MODEL,
+# or leave it for the router's auto chain + key rotation.
+export ANTHROPIC_BASE_URL="${ROUTER_URL}"
+export ANTHROPIC_AUTH_TOKEN="dummy"
+export ANTHROPIC_MODEL="${ANTHROPIC_MODEL:-auto}"
+# Use a free model for the small/fast (background) calls too.
+export ANTHROPIC_SMALL_FAST_MODEL="${ANTHROPIC_SMALL_FAST_MODEL:-auto}"
+
+echo "→ Claude Code via Auto Modal (${ROUTER_URL}), model=${ANTHROPIC_MODEL}"
+exec claude "$@"

package/config.default.yaml

@@ -0,0 +1,23 @@
+# Auto Modal — default config.
+# Edit here, or manage models live from the dashboard at http://localhost:8787/
+# ("+ Add a model" pulls each provider's catalog). Keys come from .env
+# (OPENROUTER_API_KEYS / HF_API_KEYS), comma-separated, and are rotated automatically.
+
+port: 8787
+cooldownMs: 3600000        # how long a rate-limited slot rests before retry
+transientRetries: 2        # retries on 5xx/timeout before rotating
+
+chain:                     # order = priority (tried top to bottom)
+  - id: nemotron-super-free
+    provider: openrouter
+    model: nvidia/nemotron-3-super-120b-a12b:free
+    apiKeys: ${OPENROUTER_API_KEYS}
+    dailyLimit: 50         # per key (OpenRouter free tier ~50/day)
+    rpm: 20                # per-key requests/min
+
+  # Add a HuggingFace fallback once HF_API_KEYS is set (auto-skipped until then):
+  - id: hf-qwen
+    provider: huggingface
+    model: Qwen/Qwen2.5-72B-Instruct
+    apiKeys: ${HF_API_KEYS}
+    dailyLimit: 200

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@prakashpro1/auto-modal",
+  "version": "1.0.0",
+  "description": "Local proxy that auto-switches models AND API keys when a rate/usage limit is hit. Serves both the OpenAI API (Continue) and the Anthropic Messages API (Claude Code), with a live dashboard.",
+  "type": "module",
+  "main": "src/server.js",
+  "bin": {
+    "automodal": "bin/cli.mjs"
+  },
+  "files": [
+    "src",
+    "bin",
+    "scripts",
+    "config.default.yaml",
+    ".env.example",
+    "claude-router.sh",
+    "README.md"
+  ],
+  "preferGlobal": true,
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "openrouter",
+    "huggingface",
+    "llm",
+    "proxy",
+    "router",
+    "rate-limit",
+    "fallback",
+    "api-key-rotation",
+    "continue",
+    "claude-code",
+    "anthropic",
+    "openai-compatible"
+  ],
+  "author": "prakash.saeculumsolutions@gmail.com",
+  "license": "MIT",
+  "homepage": "https://github.com/prakashpro3/pro-modal#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/prakashpro3/pro-modal.git"
+  },
+  "bugs": {
+    "url": "https://github.com/prakashpro3/pro-modal/issues"
+  },
+  "scripts": {
+    "prestart": "node scripts/free-port.mjs",
+    "start": "node src/server.js",
+    "restart": "node scripts/free-port.mjs && node src/server.js",
+    "predev": "node scripts/free-port.mjs",
+    "dev": "node --watch src/server.js",
+    "test": "node test/fallback.test.mjs && node test/rpm.test.mjs && node test/completions.test.mjs && node test/admin.test.mjs && node test/keys.test.mjs && node test/reorder.test.mjs && node test/edit-test.test.mjs && node test/history.test.mjs && node test/requested-model.test.mjs && node test/messages.test.mjs"
+  },
+  "dependencies": {
+    "dotenv": "^16.4.5",
+    "express": "^4.19.2",
+    "yaml": "^2.5.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/scripts/free-port.mjs

@@ -0,0 +1,26 @@
+// Kill any stale process already listening on the router's port, so `npm start`
+// never ends up with two instances fighting over the port + usage state.
+// Runs automatically as `prestart` / `predev` (and via `npm run restart`).
+import { execSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import YAML from "yaml";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cfgPath = process.env.ROUTER_CONFIG || join(__dirname, "..", "config.yaml");
+
+let port = 8787;
+try { port = YAML.parse(readFileSync(cfgPath, "utf8"))?.port || 8787; } catch { /* default */ }
+
+try {
+  // lsof exits non-zero when nothing is listening — that throws and we no-op.
+  const pids = execSync(`lsof -ti tcp:${port}`, { stdio: ["ignore", "pipe", "ignore"] })
+    .toString().trim().split("\n").filter(Boolean);
+  if (pids.length) {
+    execSync(`kill -9 ${pids.join(" ")}`);
+    console.log(`free-port: stopped ${pids.length} stale instance(s) on :${port} (${pids.join(", ")})`);
+  }
+} catch {
+  // Nothing on the port (or lsof unavailable) — nothing to do.
+}