9router: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

9Router (9router-app) — a local AI routing gateway + Next.js dashboard. It exposes one OpenAI-compatible endpoint (/v1/*) and routes traffic across 40+ upstream providers with format translation, model-combo fallback, multi-account fallback, OAuth/API-key credential management, token refresh, quota/usage tracking, and optional cloud sync.

Two published artifacts live in this one repo:

• The dashboard + gateway (root package.json, 9router-app) — the Next.js server that does the actual routing.
• The CLI launcher (cli/, published to npm as 9router) — a separate package that installs/starts the server and manages the tray. It has its own package.json, version, and build.

The code lives in src/ (Next.js app + dashboard/compat APIs), open-sse/ (the provider-agnostic routing/translation engine), cli/ (the launcher package), and tests/.

Commands

Dashboard/gateway (run from repo root):

cp .env.example .env
npm install
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev   # dev (webpack, port 20127 by default via next dev)
npm run build && PORT=20128 HOSTNAME=0.0.0.0 npm run start           # production

• Bun variants: npm run dev:bun / build:bun / start:bun.
• Default runtime port is 20128 (dashboard at /dashboard, API at /v1).
• Lint: npx eslint . (config eslint.config.mjs, extends eslint-config-next).

CLI package (cli/):

npm run cli:pack       # build + npm pack from root
cd cli && npm run dev  # nodemon watch

Tests (vitest, in tests/, an independent ESM package — not wired into root npm test):

npm install                             # ROOT deps first — tests import from src/ which needs `open`, `undici`, etc.
cd tests && npm install                 # then tests' own deps (vitest) → tests/node_modules (allowed by tests/.gitignore)
npx vitest run                          # all tests; auto-discovers tests/vitest.config.js
npx vitest run unit/capabilities.test.js   # single file (path relative to tests/)

The committed tests/package.json test script hardcodes Unix paths (NODE_PATH=/tmp/node_modules …) — a shared-install workaround from upstream. On Windows (or anywhere), ignore it and use the npx vitest form above; vitest.config.js resolves the open-sse/@/ aliases from the repo root regardless of where vitest lives.

The suite is NOT expected to be all-green on a plain checkout. ~938 pass, ~64 fail. Judge regressions with tests/__baseline__/verify-no-regression.mjs, not a raw run. Expected red:

• 26 catalogued in tests/__baseline__/known-fails.txt (rtk, oauth-cursor-auto-import, translator-request-normalization, …).
• unit/embeddings.cloud.test.js imports cloud/src/handlers/embeddings.js — the cloud/ worker dir is not in this repo, so it always fails here.
• unit/xai-oauth-service.test.js times out (5s) when the xAI endpoint-discovery fetch isn't reachable/mocked.
• real/*.real.test.js make live provider calls — need credentials, skip otherwise.

• *.real.test.js under tests/translator/real/ make live provider calls — skip unless credentials are set.
• Regression baselines: tests/__baseline__/verify-*.mjs compare against committed snapshots (providers, aliases, OAuth URLs). Run these after touching provider registry / alias logic.