Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors
OmniRoute agent guide
Single source of truth. This file holds ALL project rules, conventions, architecture notes and Hard Rules for every AI assistant working this repository (Claude Code, Gemini, Codex, Copilot, and any other agent).
CLAUDE.mdandGEMINI.mdonly add assistant-specific deltas and point back here. When a rule needs to change, change it HERE — never re-fork it into an assistant-specific file.
Quick Start
npm install # Install deps (auto-generates .env from .env.example)
npm run dev # Dev server at http://localhost:20128
npm run build # Production build (Next.js 16 standalone)
npm run build:release # Release build
npm run lint # ESLint (0 errors expected; warnings are pre-existing)
npm run typecheck:core # TypeScript check (should be clean)
npm run typecheck:noimplicit:core # Strict check (no implicit any)
npm run test:coverage # Unit tests + coverage gate (67.33 / 67.33 / 72.02 / 65.08 — statements/lines/functions/branches, enforced by the blocking ratchet in config/quality/quality-baseline.json; test:coverage itself hardcodes 60)
npm run check # lint + test combined
npm run check:cycles # Detect circular dependencies (advisory — lists the SCCs)
npm run check:cycles:ratchet # Same scan, blocking above the quality-baseline ceiling
npm run check:docs-all # Run after changing documentation (includes fabricated-docs validation)
Running tests: see Testing below (run the most focused test for changed code first).
Project at a Glance
OmniRoute — unified AI proxy/router. One endpoint, 375 LLM providers, auto-fallback.
- API Routes —
src/app/api/v1/(Next.js App Router entry points) - Handlers —
open-sse/handlers/(request processing: chat, embeddings, etc) - Executors —
open-sse/executors/(provider-specific HTTP dispatch) - Translators —
open-sse/translator/(format conversion OpenAI↔Claude↔Gemini) - Transformer —
open-sse/transformer/(Responses API ↔ Chat Completions) - Services —
open-sse/services/(combo routing, rate limits, caching, etc) - Database —
src/lib/db/(SQLite domain modules, 209 migrations) - Domain/Policy —
src/domain/(policy engine, cost rules, fallback logic) - MCP Server —
open-sse/mcp-server/(110 tools: 45 canonical + memory/skill/GitHub/pool/gamification/plugin/Notion/Obsidian/local-corpus/RTK modules; 3 transports: stdio / SSE / Streamable HTTP; 33 scopes) - A2A Server —
src/lib/a2a/(JSON-RPC 2.0 agent protocol) - Skills —
src/lib/skills/(extensible skill framework); Memory —src/lib/memory/(persistent conversational memory)
Monorepo: src/ (Next.js 16 app), open-sse/ (streaming engine workspace), electron/ (desktop app), tests/, bin/ (CLI entry point).
Request Pipeline
Client → /v1/chat/completions (Next.js route)
→ CORS → Zod validation → auth? → policy check → prompt injection guard
→ handleChatCore() [open-sse/handlers/chatCore.ts]
→ cache check → rate limit → combo routing?
→ resolveComboTargets() → handleSingleModel() per target
→ translateRequest() → getExecutor() → executor.execute()
→ fetch() upstream → retry w/ backoff
→ response translation → SSE stream or JSON
→ If Responses API: responsesTransformer.ts TransformStream
API routes follow a consistent pattern: Route → CORS preflight → Zod body validation → Optional auth (extractApiKey/isValidApiKey) → API key policy enforcement → Handler delegation (open-sse). No global Next.js middleware — interception is route-specific.
Combo routing (open-sse/services/combo.ts): 20 public strategies (priority, weighted, fill-first, round-robin, p2c, random, least-used, cost-optimized, reset-aware, reset-window, headroom, quota-weighted, strict-random, auto, lkgp, context-optimized, cache-optimized, context-relay, fusion, pipeline). Each target calls handleSingleModel() (wraps handleChatCore() with per-target error handling + circuit breaker checks); the fusion strategy instead fans out to a panel of models in parallel and a judge model synthesizes one final answer (open-sse/services/fusion.ts). 16-factor Auto-Combo scoring + full strategy table: docs/routing/AUTO-COMBO.md; the 3 resilience layers: docs/architecture/RESILIENCE_GUIDE.md.
Resilience Runtime State
Three related but distinct temporary-failure mechanisms — keep their scope separate when debugging routing:
- Provider Circuit Breaker — scope: whole provider. 4 states (CLOSED/DEGRADED/OPEN/HALF_OPEN); lazy recovery —
getStatus()/canExecute()refresh an expiredOPEN, no background timer. - Connection Cooldown — scope: one connection/account/key. Lazy
rateLimitedUntilskip + exponential backoff; terminal states (banned/expired/credits_exhausted) are NOT cooldowns. - Model Lockout — scope: provider + connection + model. One bad model never disables the whole connection (
open-sse/services/accountFallback.ts).
Defaults: open-sse/config/constants.ts → PROVIDER_PROFILES (overridable via
OMNIROUTE_PROVIDER_BREAKER_* / OMNIROUTE_CIRCUIT_BREAKER_*). Only provider-level statuses
408/500/502/503/504 trip the provider breaker — most 401/403/429 belong to connection
cooldown or model lockout. Full agent reference (files, states, thresholds, debugging):
docs/architecture/RESILIENCE_GUIDE.md → "Runtime state — agent quick reference".
Repository map
Read the nearest AGENTS.md and the linked deep-dive before making a non-trivial change.
- API routes —
src/app/api/v1/→docs/architecture/ARCHITECTURE.md - Streaming request handling —
open-sse/handlers/→docs/architecture/ARCHITECTURE.md - Provider execution and translation —
open-sse/executors/,open-sse/translator/→docs/architecture/CODEBASE_DOCUMENTATION.md - Routing and resilience —
open-sse/services/→open-sse/services/AGENTS.md,docs/routing/AUTO-COMBO.md - Database and migrations —
src/lib/db/,src/lib/db/migrations/→src/lib/db/AGENTS.md - Domain policy —
src/domain/→docs/architecture/ARCHITECTURE.md - MCP and A2A —
open-sse/mcp-server/,src/lib/a2a/→docs/frameworks/MCP-SERVER.md,docs/frameworks/A2A-SERVER.md - Agent features —
src/lib/{acp,memory,skills,cloudAgent}/→docs/frameworks/AGENT_PROTOCOLS_GUIDE.md,docs/frameworks/SKILLS.md - Safety and governance —
src/lib/{guardrails,compliance}/,src/server/authz/→docs/security/GUARDRAILS.md,docs/architecture/AUTHZ_GUIDE.md - Operations —
src/mitm/, tunnel modules,electron/→docs/ops/TUNNELS_GUIDE.md,docs/guides/ELECTRON_GUIDE.md
File placement & repo-root hygiene
- Test files: ALL unit tests, integration tests, ecosystem tests, or Vitest files MUST strictly be placed within the
tests/directory (e.g.,tests/unit/,tests/integration/). NEVER create test files in the project root (/). - Scripts and utilities: ALL maintenance, debugging, generation, or experimental scripts (
.cjs,.mjs,.js,.ts) MUST be placed strictly inside one of thescripts/subfolders (build/,dev/,check/,docs/,i18n/,ad-hoc/,quality/,release/,ci/,ops/,perf/,research/,sre/,vps/,homolog/,packs/,skills/,test/,cli/,compression/,compression-eval/,devin-bridge/,docker/,features/,router-eval/). One-shot or experimental code goes underscripts/ad-hoc/. NEVER dump loose scripts in the project root (/) or the top-levelscripts/folder.
The project root MUST ONLY contain:
- Configuration files (
vitest.config.ts,next.config.mjs,eslint.config.mjs,tsconfig*.json,playwright.config.ts,prettier.config.mjs,postcss.config.mjs,sonar-project.properties,fly.toml,docker-compose*.yml,Dockerfile) - Dependency files (
package.json,package-lock.json) - Documentation files (
README.md,CHANGELOG.md,ROADMAP.md,LICENSE,AGENTS.md,CLAUDE.md,GEMINI.md,CONTRIBUTING.md,SECURITY.md,CODE_OF_CONDUCT.md,llm.txt) - CI/CD files and ignore definitions (
.gitignore,.dockerignore,.npmignore,.npmrc,.node-version,.nvmrc,.env.example)
When creating any validation tests or one-off logic scripts, default to scripts/ad-hoc/ or tests/unit/ according to your goals. Do not pollute the / root context.
- Root
_*paths are private and NEVER tracked (_tasks/,_references/,_mono_repo/,_ideia/,_cache/and any future_<name>): they live on disk only, are gitignored by the anchored patterns/_*/+/_*, and some are full git repositories of their own (_tasks→ private remote_tasks_omniroute). Nevergit addanything inside them (a plainaddis already blocked by the ignore; never use-f), and never "clean them up" from the main repo — untracking is done withgit rm --cachedso the disk content stays. Thecheck:tracked-artifactsgate (pre-commit + CI) fails on ANY tracked root path starting with_, present or future. See Hard Rule #23 for the_tasksspecifics.
Key Conventions
Code Style
- 2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas (enforced by lint-staged via Prettier) — run Prettier on changed files
- Imports: external → internal (
@/,@omniroute/open-sse) → relative - Naming: files=camelCase/kebab, components=PascalCase, constants=UPPER_SNAKE
- ESLint:
no-eval,no-implied-eval,no-new-func= error everywhere;no-explicit-any= error inopen-sse/andtests/(since #6218 — pre-existing violations are frozen inconfig/quality/eslint-suppressions.json, new ones must be fixed;npm run lintapplies the suppressions and is what CI runs) - TypeScript:
strict: false, target ES2022, module esnext, resolution bundler. Prefer explicit types.
Database
- Always go through
src/lib/db/domain modules — never write raw SQL in routes or handlers - Never barrel-import from
localDb.ts— import specificsrc/lib/db/*modules - DB singleton:
getDbInstance()fromsrc/lib/db/core.ts(WAL journaling) - Migrations:
src/lib/db/migrations/— versioned SQL files, idempotent, run in transactions
Error Handling
- try/catch with specific error types, log with pino context
- Never swallow errors in SSE streams — use abort signals for cleanup
- Return proper HTTP status codes (4xx/5xx)
Security
- Never use
eval(),new Function(), or implied eval - Validate all inputs with Zod schemas
- Encrypt credentials at rest (AES-256-GCM); never log SQLite encryption keys
- Sanitize user HTML with DOMPurify
- Upstream header denylist:
src/shared/constants/upstreamHeaders.ts— keep sanitize, Zod schemas, and unit tests aligned when editing - Public upstream credentials (for example, OAuth client_id/secret values or Firebase Web keys extracted from public CLIs): MUST be embedded via
resolvePublicCred()fromopen-sse/utils/publicCreds.ts— never as string literals. Seedocs/security/PUBLIC_CREDS.mdfor the mandatory pattern. - Error responses (HTTP / SSE / executor / MCP handler): MUST route through
buildErrorBody()orsanitizeErrorMessage()fromopen-sse/utils/error.ts— never put rawerr.stackorerr.messagein a response body. Seedocs/security/ERROR_SANITIZATION.md. - Shell commands built from variables: when calling
exec()/spawn()with a script that needs runtime values, pass them via theenvoption (shell-escaped automatically) — never string-interpolate untrusted/external paths into the script body. Reference:src/mitm/cert/install.ts::updateNssDatabases. - Secure-by-default libraries (tldrsec/awesome-secure-defaults): prefer Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink over custom implementations whenever adding new security-sensitive surfaces.
Documentation accuracy
Documentation must describe verified behavior, not plausible behavior.
- Before documenting an API name, endpoint, path, CLI command, or environment variable,
search for it:
rg -n "name" src/ open-sse/ bin/. If it has no source match, do not document it. - Measure mutable counts instead of writing them from memory: use
wc -l <file>or a directory-specific count command. - Copy code examples from working usage or run them. Prefer a source link such as
path/to/file.ts:lineto an invented signature. - Run
npm run check:docs-allfor edits underdocs/; it includes the fabricated-docs validation.
Common Modification Scenarios
Full step-by-step recipes: docs/architecture/MODIFICATION_SCENARIOS.md. Quick index:
- New provider: check
docs/reference/REMOVED_PROVIDERS.mdfirst (blocklist-guarded — never reintroduce), thensrc/shared/constants/providers.ts→ executor → translator → OAuth config (resolvePublicCred(), never a literal) →open-sse/config/providerRegistry.ts→ tests. - Dual auth (multiple API keys) for a provider: add its ID to
DUAL_AUTH_PROVIDER_IDS(src/shared/constants/providers.ts) + update itsauthHint; each key becomes its own connection row, rotated bygetProviderCredentials(). - New API route:
src/app/api/v1/<route>/route.ts— CORS → Zod → optional auth → handler inopen-sse/handlers/; errors viabuildErrorBody(); tests assert no stack-trace leak. - New DB module:
src/lib/db/<module>.ts(getDbInstance) → migration if new tables → tests. - New MCP tool:
open-sse/mcp-server/tools/(Zod schema) → register → scope → tests. - New A2A skill:
src/lib/a2a/skills/→A2A_SKILL_HANDLERS→ Agent Card → tests + doc table. - New cloud agent:
src/lib/cloudAgent/agents/(extendsCloudAgentBase) →registry.ts→ OAuth → tests + doc. - New embedded service: installer →
bootstrap.ts→ DB seed → 8 API endpoints +isLocalOnlyPath()guard → UI tab → docs + OpenAPI → tests. - Guardrail / eval / skill / webhook / log-export destination: see the detail doc.
Reference Documentation
For any non-trivial change, read the matching deep-dive first:
- Repo navigation —
docs/architecture/REPOSITORY_MAP.md· Architecture —docs/architecture/ARCHITECTURE.md· Engineering reference —docs/architecture/CODEBASE_DOCUMENTATION.md - Auto-Combo (16-factor scoring, 20 strategies) —
docs/routing/AUTO-COMBO.md· Reasoning replay —docs/routing/REASONING_REPLAY.md - Resilience (3 mechanisms + debugging) —
docs/architecture/RESILIENCE_GUIDE.md - Modification recipes —
docs/architecture/MODIFICATION_SCENARIOS.md - Skills framework —
docs/frameworks/SKILLS.md· Radar (free-model catalog overlay) —docs/frameworks/RADAR.md· Memory system (FTS5 + Qdrant) —docs/frameworks/MEMORY.md - Cloud agents —
docs/frameworks/CLOUD_AGENT.md· Agent protocols (A2A / ACP / Cloud) —docs/frameworks/AGENT_PROTOCOLS_GUIDE.md - Guardrails (PII / injection / vision) —
docs/security/GUARDRAILS.md· Public upstream credentials (Gemini/etc.) —docs/security/PUBLIC_CREDS.md· Error message sanitization —docs/security/ERROR_SANITIZATION.md· Compliance / audit —docs/security/COMPLIANCE.md· Stealth (TLS / fingerprint) —docs/security/STEALTH_GUIDE.md - Evals —
docs/frameworks/EVALS.md· Webhooks —docs/frameworks/WEBHOOKS.md· Log export (call logs → BigQuery/…) —docs/frameworks/LOG-EXPORT.md - Authorization pipeline —
docs/architecture/AUTHZ_GUIDE.md - MCP server —
docs/frameworks/MCP-SERVER.md· A2A server —docs/frameworks/A2A-SERVER.md - API reference + OpenAPI —
docs/reference/API_REFERENCE.md+docs/openapi.yaml· Provider catalog (auto-generated) —docs/reference/PROVIDER_REFERENCE.md - Tunnels —
docs/ops/TUNNELS_GUIDE.md· Release flow —docs/ops/RELEASE_CHECKLIST.md· Worktree protocol —docs/ops/WORKTREE_ISOLATION.md· Hard Rules detail —docs/ops/HARD_RULES_DETAIL.md· Build warnings + Bun troubleshooting —docs/ops/BUILD_WARNINGS.md - Electron desktop app —
docs/guides/ELECTRON_GUIDE.md· VS Code Copilot Chat (OmniCopilot extension) —docs/guides/VSCODE-COPILOT.md - Embedded services —
docs/frameworks/EMBEDDED-SERVICES.md· Quality gates (~90 scripts, allowlist policy) —docs/architecture/QUALITY_GATES.md
Testing
- Unit tests —
npm run test:unit; single file (Node native test runner — most tests) —node --import tsx/esm --test tests/unit/your-file.test.ts - Vitest (MCP server, autoCombo, cache) —
npm run test:vitest; all suites —npm run test:all - E2E (Playwright) —
npm run test:e2e; Protocol E2E (MCP+A2A) —npm run test:protocols:e2e(CI jobtest-protocols-e2e, advisory — #10049); Ecosystem —npm run test:ecosystem(CI jobtest-ecosystem, blocking) - Coverage gate —
npm run test:coverage(67.33 / 67.33 / 72.02 / 65.08 — statements/lines/functions/branches, enforced by the blocking ratchet in config/quality/quality-baseline.json; test:coverage itself hardcodes 60); report —npm run coverage:report - Full test matrix:
CONTRIBUTING.md→ "Running Tests"
PR rule: If you change production code in src/, open-sse/, electron/, or bin/, you must include or update tests in the same PR.
Test layer preference: unit first → integration (multi-module or DB state) → e2e (UI/workflow only). Encode bug reproductions as automated tests before or alongside the fix.
Both test runners must pass: npm run test:unit and npm run test:vitest cover non-overlapping files; both are CI jobs (test-unit, test-vitest) and must be green before merging — one green suite may silently ship broken MCP tools or routing regressions.
Bug fix / issue triage protocol (Hard Rule #18): failing-then-passing test (TDD, preferred) OR a documented live test on the production VPS ([email protected]) recorded in the PR; touch only what the failing test proves broken. Decision tree: docs/ops/HARD_RULES_DETAIL.md → Rule 18.
Copilot coverage policy: When a PR changes production code and coverage is below 60% (statements/lines/functions/branches), do not just report — add or update tests, rerun the coverage gate, then ask for confirmation. Include commands run, changed test files, and final coverage result in the PR report.
Review focus
- Keep database operations in
src/lib/db/; do not issue raw SQL from routes. - Send provider requests through
open-sse/handlers/. - Keep MCP and A2A pages as tabs inside
/dashboard/endpoint. - Preserve SSE cleanup, rate-limit header parsing, Zod validation, and provider-schema validation.
- Treat Memory and Skills as cross-cutting changes that can affect MCP tools, the request pipeline, and A2A skills.
- Do not close a contributor pull request after using its code; merge it through GitHub so the contributor receives credit.
- Never merge a PR that touches an agent-instruction surface without explicit operator
approval —
CLAUDE.md,AGENTS.md,GEMINI.md,llm.txt(+ mirrors) andskills/**/SKILL.mdare executed as authority by every AI session; a merged instruction compromises every future agent run. Check withgh pr diff <N> --name-onlybefore any merge. Incident record: PR #11770 (2026-09-01) told agents to execute a third-party setup script and was swept in by a merge campaign; reverted in #12249.
Planning & Research Artifacts
_tasks/ is a separate, isolated git repository that is gitignored by the main repo (.gitignore → _tasks/) — the canonical home for working artifacts (plans, specs/designs, research, hand-offs), versioned in their own repo instead of polluting the main OmniRoute tree. Hard rule — never write planning / research output under docs/ or the repo root. Whenever any plan/spec/research generator runs in this project (superpowers or otherwise), save to _tasks/ using the filename convention:
| Artifact | Save here |
|---|---|
| Plans | _tasks/superpowers/plans/YYYY-MM-DD-<feature>.md |
| Specs / design | _tasks/superpowers/specs/YYYY-MM-DD-<topic>-design.md |
| Research | _tasks/research/… |
| Hand-offs | _tasks/hands-off/<YYYY-MM-DD>_<branch>_v<versão>_sess-<id>/ |
Commit those artifacts inside the _tasks/ repo (git -C _tasks …), never in the main repo.
Git Workflow
# Never commit directly to main
git checkout -b feat/your-feature
git commit -m "feat: describe your change"
git push -u origin feat/your-feature
Branch prefixes: feat/, fix/, refactor/, docs/, test/, chore/
Commit format (Conventional Commits): feat(db): add circuit breaker — scopes: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills
Husky hooks:
- pre-commit: lint-staged +
check-docs-sync+check:any-budget:t11+check:tracked-artifacts - commit-msg:
check:ai-attribution— rejects AI/botCo-Authored-Bytrailers and AI-generation footers in the message (Hard Rule #16; human co-authors allowed; also in thequality.ymlfast-gates loop (PR→release/**) and a PR-onlyci.ymllint step (PR→main) — #14436) - pre-push: intentionally light (PATH/npm sanity only) —
any-budget+tracked-artifactsalready run on pre-commit and CI still enforces both; re-running them per push was pure double-pay (was Fase 6A.12 full pre-push gate; folded into pre-commit in #6716).
Worktree isolation (MANDATORY for every development task)
Hard Rule #19: one worktree + dedicated branch per task, base branch confirmed with the
operator first (usually the active release/vX.Y.Z). Non-negotiables:
- 🔴 Worktrees live ONLY under
.claude/worktrees/— anywhere else escapes the tsconfig /.dockerignorebuild-scope excludes (tsconfiginclude: **/*globs ~70× the codebase →next buildOOM, incident 2026-06-25) and scatters worktrees. - Reuse the main checkout's node_modules via hard links (
cp -al), neverln -s— Turbopack FATALs on a symlink resolving outside the project root while typecheck/lint/tests keep passing (incident 2026-07-31, #9043). - Copy the gitignored
.husky/_too (cp -a <main>/.husky/_ .husky/_) — without it no pre-commit gate runs and nothing says so (59 commits slipped pastscripts/check/check-git-identity.sh, 2026-08-29 → 09-02). Preferscripts/dev/new-worktree.sh <branch> [base], which does all of this and verifies the hook. - Work, commit, push, open the PR — all from inside the worktree.
- Tear down only your own worktree + branch, by name (never
fix/*/feat/*wildcards — other sessions keep their own). Leave any worktree you didn't create untouched. - End every session with the main checkout back on the branch it started on.
Full protocol with commands and incident history:
docs/ops/WORKTREE_ISOLATION.md.
Base-green check (PRs must not be born red)
Before cutting a branch, merging the base into a PR branch, mass-retargeting PRs, or opening a
PR, check the base tip's 🔴 Release branch not green: <branch> issue (label base-red):
gh issue list --repo diegosouzapw/OmniRoute --state open --search "Release branch not green: <base> in:title".
If red: never treat or "fix" the inherited failures in your branch (a base-red fix is its own
freeze-gated fix/release-vX.Y.Z-basereds PR); a PR opened anyway carries
⚠️ base-red inherited: #<issue> in its body. Full procedure: docs/ops/WORKTREE_ISOLATION.md.
Sync-back landings are fast-forward, never squash
A main → release/vX+1 sync-back lands as the merge commit it already is
(git push origin <head>:refs/heads/release/vX+1), never squashed — a squash drops main from
the release ancestry and the next sync-back re-conflicts on every file (551 on v3.8.50 → v3.8.51).
After landing, git merge-base --is-ancestor origin/main origin/release/vX+1 must be true.
Steps + baseline-freeze check: docs/ops/WORKTREE_ISOLATION.md → "Sync-back landings".
Upstream contributions
This checkout is a fork of diegosouzapw/OmniRoute. Keep fork-only deployment and personal automation changes out of upstream PRs. Start upstream work from the active upstream default branch, not main (git fetch upstream && git switch -c <branch-name> upstream/<default-branch>), target that same release branch in the PR, stage only the intended files, run the focused checks, and use a Conventional Commit message (for example, docs: slim AGENTS.md).
Environment
- Runtime: Node.js ≥22.22.2 <23 || ≥24.0.0 <27, ES Modules — the only supported runtime for the published
omnirouteCLI, the server, and the test suites (node:test+ vitest);engines.nodeis authoritative and end users never need Bun. A best-effortbun:sqlitecompatibility path exists so a global Bun install (bun install -g omniroute) can start withoutbetter-sqlite3(driver adapter + Bun-aware process spawning); it is not a supported runtime — no support guarantees — and every Bun-specific runtime change MUST preserve the Node driver/fallback chain and ship a Bun test (test:bun:db) or an explicit reason why the path is Node-only. - Bun (build/dev script runner + compatibility smoke only): Bun
1.4.2is pinned as an exact devDependency (provisioned through the existingnpm civia the lockfile's@oven/bun-*platform binaries — nosetup-bun/ad-hoc install). It executes only an allow-listed set of TypeScript gate/generator scripts (replacingnode --import tsxfor startup speed): the CI checkscheck:provider-consistency,check:compression-budget,check:known-symbols; the non-CIgen:provider-reference,bench:compression; plus thetest:bun:dbcompatibility smoke suite. Do NOT widen Bun tonpm install, the build (build:cli*),check:pack-artifact, the supported published runtime, or the main test runners — those stay on Node. Any new Bun-invoking script must be validated byte-identical against itsnode --import tsxoutput first. Bun failing (bun: not found, or the skipped-postinstallplaceholder binary):docs/ops/BUILD_WARNINGS.md→ "Bun script-runner failures". - TypeScript: 6.0+, target ES2022, module esnext, resolution bundler
- Path aliases:
@/*→src/,@omniroute/open-sse→open-sse/,@omniroute/open-sse/*→open-sse/* - Default port: 20128 (API + dashboard on same port)
- Data directory:
DATA_DIRenv var, defaults to~/.omniroute/ - Key env vars:
PORT,JWT_SECRET,API_KEY_SECRET,INITIAL_PASSWORD,REQUIRE_API_KEY,APP_LOG_LEVEL - Setup:
cp .env.example .envthen generateJWT_SECRET(openssl rand -base64 48) andAPI_KEY_SECRET(openssl rand -hex 32)
Quality Gates & Ratchets
OmniRoute has ~90 quality-gate scripts (scripts/check/ + scripts/quality/) wired across 9 gate-running jobs in .github/workflows/ci.yml, plus the quality.yml fast-gates job (PR→release/**) and 5 quality nightly workflows. Full inventory, per-job breakdown, and operational procedures: docs/architecture/QUALITY_GATES.md.
Quick reference:
- Gates in jobs
lint+docs-sync-strict: pass/fail policy gates — fix the violation or add an allowlist entry with a justification comment + tracking issue. - Gates in job
quality-gate: ratchet — metrics (ESLint warnings, code coverage, duplication, complexity) must not regress vsquality-baseline.json. Update vianpm run quality:ratchet -- --updatewhen a metric genuinely improves. - Job
test-vitestrunsnpm run test:vitest(MCP tools, autoCombo, cache) — blocking.test:vitest:uihas been blocking since PR #7127. - Velocity phase (2026-08-30 → v4.0): every numeric baseline is loosened by 20% and
--require-tightenis advisory (quality-baseline.json→_policy); the nightlybaseline-headroomjob tracks how much of the budget is left in the issue "📈 Baseline headroom". Seedocs/architecture/QUALITY_GATES.md→ "Velocity phase".
Allowlist policy (short form): fix the cause; use the allowlist only for pre-existing violations you cannot fix in the same PR (comment with justification + issue number). Stale entries are caught by the stale-enforcement added in Fase 6A.3.
Hard Rules
Rule numbers are stable and cited across scripts and docs — never renumber. Where a rule below
is a short form, its complete binding text, rationale and incident history are in
docs/ops/HARD_RULES_DETAIL.md under the same number.
Never commit secrets or credentials
Never barrel-import from
localDb.ts— import specificsrc/lib/db/*modulesNever use
eval()/new Function()/ implied evalNever commit directly to
mainNever write raw SQL in routes — use
src/lib/db/modulesNever silently swallow errors in SSE streams
Always validate inputs with Zod schemas
Always include tests when changing production code
Coverage must not regress below the baseline frozen in
quality-baseline.json(ratchet); absolute floor is 60% (statements/lines/functions/branches). Update the baseline vianpm run quality:ratchet -- --updateonly when coverage genuinely improves. Seedocs/architecture/QUALITY_GATES.md.Never bypass Husky hooks (
--no-verify,--no-gpg-sign) without explicit operator approval.Never embed public upstream OAuth client_id/secret or Firebase Web keys as string literals — always go through
resolvePublicCred()(open-sse/utils/publicCreds.ts). Seedocs/security/PUBLIC_CREDS.md.Never return raw
err.stack/err.messagein HTTP / SSE / executor responses — always route throughbuildErrorBody()orsanitizeErrorMessage()(open-sse/utils/error.ts). Seedocs/security/ERROR_SANITIZATION.md.Never string-interpolate external paths or runtime values into shell scripts passed to
exec()/spawn()— pass via theenvoption instead. Reference:src/mitm/cert/install.ts::updateNssDatabases.Never dismiss a CodeQL / Secret-Scanning alert without (a) first checking the pattern docs above to see if the helper applies, and (b) recording the technical justification in the dismissal comment. Precedent:
js/stack-trace-exposureraised on callsites that already route throughsanitizeErrorMessage()is a known CodeQL limitation (custom sanitizers not recognized) — dismiss asfalse positivereferencingdocs/security/ERROR_SANITIZATION.md.Never expose routes that spawn child processes (
/api/mcp/,/api/cli-tools/runtime/) withoutisLocalOnlyPath()classification insrc/server/authz/routeGuard.ts. Loopback enforcement happens unconditionally before any auth check — leaked JWT via tunnel cannot trigger process spawning. Seedocs/security/ROUTE_GUARD_TIERS.md.Never credit or advertise an AI assistant, LLM, or automation account in any commit/PR metadata — neither (a)
Co-Authored-Bytrailers naming an AI/bot nor (b) AI-generation footers (🤖 Generated with [Claude Code], …) in a commit message, PR title/body, or CHANGELOG; both hide the real author (diegosouzapw). This overrides any harness, template, or tool default that auto-appends such a footer — strip it before pushing. Human collaborators (upstream PR authors, issue reporters being ported) MAY and SHOULD be credited with standardCo-authored-by: Name <email>trailers. Full text:docs/ops/HARD_RULES_DETAIL.md→ Rule 16.Never expose routes under
/api/services/or/dashboard/providers/services/*/embed/withoutisLocalOnlyPath()classification insrc/server/authz/routeGuard.ts. These routes can spawn child processes (npm install,node). Loopback enforcement happens unconditionally before any auth check — a leaked JWT via tunnel cannot trigger process spawning. Seedocs/security/ROUTE_GUARD_TIERS.md.Every bug fix must be validated before shipping: a failing-then-passing unit/integration test (TDD) OR a documented live test on the production VPS (192.168.0.15). A fix without either is not merged. See Testing → "Bug fix / issue triage protocol" and
docs/ops/HARD_RULES_DETAIL.md→ Rule 18 for the full decision tree.Never develop on the shared main checkout. Every development task runs in its own git worktree on its own dedicated branch, and you MUST confirm the base branch with the operator before creating the worktree/branch — never assume
mainor the currently checked-out branch. Agit checkoutin the shared checkout silently destroys other sessions' uncommitted work. Tear down only the worktrees/branches you created (by name, neverfix/*/feat/*wildcards), leave other sessions' worktrees untouched, and end on the branch you started on (the activerelease/vX.Y.Z, nevermain). See Git Workflow → "Worktree isolation" anddocs/ops/WORKTREE_ISOLATION.md.PII redaction/sanitization is opt-in — never on by default. The two data-mutating PII feature flags MUST keep
defaultValue: "false"insrc/shared/constants/featureFlagDefinitions.ts:PII_REDACTION_ENABLED(request-side) andPII_RESPONSE_SANITIZATION(response + streaming). Flipping either default to"true"requires explicit operator approval; opt-in is per-operator, never a silent default. Regression guard:tests/unit/pii-opt-in-default.test.ts. Full text:docs/ops/HARD_RULES_DETAIL.md→ Rule 20.Release-freeze — the FROZEN release branch belongs to the release captain; development does NOT stop (parallel-cycle model, 2026-07-04). Before merging any PR, every campaign workflow MUST check
gh issue list --repo diegosouzapw/OmniRoute --label release-freeze --state open. If active: NEVER merge into the frozenrelease/vX.Y.Z— retarget the PR to the highestrelease/v*(gh pr edit <N> --base release/vX+1, then VERIFY withgh pr view <N> --json baseRefName— the edit fails silently) and merge normally; HOLD only when the highest release/v* branch IS the frozen one. ⛔ ONLY/generate-releasemay raise a release-freeze (Phase 0a; lifted at Phase 12c) — never open, extend, re-open or close one autonomously (any other freeze needs the operator's explicit yes). Full text:docs/ops/HARD_RULES_DETAIL.md→ Rule 21.Cross-session safety — this repo is worked by MANY parallel sessions/agents at once; never step on another's in-flight work. Two absolute bans (both recurring incidents):
- (a) Never
git stash/git stash pop— ANYWHERE in this repo, including inside an isolated worktree, and including inside any subagent you dispatch.git stashoperates on the shared repository object store, not the per-worktree working tree — a stash in one session can silently clobber or resurrect another parallel session's uncommitted changes. Compare against a base ref withgit show <ref>:<path>orgit diff <ref> -- <path>instead — never stash your tree away to "get it clean". Put this ban verbatim in the prompt of every subagent that touches git. - (b) Never merge, push, rebase, or force-push a PR / branch / worktree that another session is actively working — including a PR whose head is a live fix worktree in
.claude/worktrees/you did not create, even when it shares yourdiegosouzapwidentity: HOLD, let the owning session merge it. Before merging or pushing to any PR you did not create this session, rungit worktree listand re-checkgh pr view <N> --json state,headRefOid. (Reinforces Rule #19.)
Full text + incidents:
docs/ops/HARD_RULES_DETAIL.md→ Rule 22.- (a) Never
_tasks/é INTOCÁVEL como estrutura — append/edit-only. É um repositório git SEPARADO (remote privadodiegosouzapw/_tasks_omniroute) montado como diretório real na raiz do checkout principal. Regras absolutas: (a) NUNCA mover, renomear, deletar, esvaziar ou transformar_tasksem symlink; sessões só podem CRIAR ou EDITAR arquivos dentro dele; (b) NUNCA rastrear_tasks(nem como symlink) no repo principal — o blob rastreado foi a causa-raiz de DOIS wipes (2026-08-08 e 2026-08-10); (c) após qualquer escrita relevante,git -C _tasks add -A && git -C _tasks commit && git -C _tasks push— o push frequente é o backup real; (d) repetir esta proibição VERBATIM no prompt de todo subagente que toque git; (e) se_tasksaparecer como symlink quebrado, NÃO commitar nada — restaurar do remote e avisar o operador. O gatecheck:tracked-artifacts(pre-commit + CI) bloqueia_tasksrastreado em qualquer forma. Texto completo:docs/ops/HARD_RULES_DETAIL.md→ Rule 23.
PII & Stream Sanitization Learnings
1. Regex Security (ReDoS)
All regex patterns matching variable-length strings (e.g. IPv6 address, credit cards) must use strictly bounded, non-overlapping sequences (e.g., limit occurrences with bounded ranges {1,7}) to prevent catastrophic backtracking when processing untrusted inputs.
2. SSE Snapshot Handling
When parsing streaming LLM responses (e.g. Responses API), check if a chunk represents a final snapshot (done or completed events). Snapshot text must be sanitized directly as a standalone string (bypassing rolling delta buffers) to prevent text duplication at the end of the stream.
3. Database Handles in Tests
Ensure that any unit tests that trigger database migrations or establish SQLite connections call resetDbInstance() and properly clean up/close all DB handles in a test.after(...) hook. Failure to release database connection handles will cause Node's native test runner to hang indefinitely.
Local development access
Dashboard at the operator's chosen URL/port (default http://localhost:20128). Credentials are operator-specific: the initial admin password is read from INITIAL_PASSWORD on first install (defaults to CHANGEME in .env.example; rotate immediately after first login); for local VPS / shared dev environments, ask the operator — credentials live in their personal vault, NOT in this repo. Any credential observed in a previous version of this file was a non-production demo value; treat it as compromised and do not reuse it.
This is NOT the Next.js you know
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.
This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.