OmniRoute/CLAUDE.md

CLAUDE.md — AI Agent Session Bootstrap

Quick-start context for AI coding agents. For deep architecture details, see AGENTS.md. For contribution workflow, see CONTRIBUTING.md.

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 lint         # ESLint (0 errors expected; warnings are pre-existing)
npm run typecheck:core  # TypeScript check (should be clean)
npm run test:coverage   # Unit tests + coverage gate (60% min)
npm run check        # lint + test combined

Running a Single Test

# Node.js native test runner (most tests)
node --import tsx/esm --test tests/unit/your-file.test.mjs

# Vitest (MCP server, autoCombo, cache)
npm run test:vitest

---

Project at a Glance

OmniRoute — unified AI proxy/router. One endpoint, 100+ LLM providers, auto-fallback.

Layer	Location	Purpose
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)
Services	open-sse/services/	Combo routing, rate limits, caching, etc
Database	src/lib/db/	SQLite domain modules (22 files)
Domain/Policy	src/domain/	Policy engine, cost rules, fallback logic
MCP Server	open-sse/mcp-server/	25 tools, 3 transports, 10 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
UI Components	src/shared/components/	React components (Tailwind CSS v4)
Provider Consts	src/shared/constants/	Provider registry (Zod-validated)
Validation	src/shared/validation/	Zod v4 schemas
Tests	tests/	Unit, integration, e2e, security, load

Monorepo Layout

OmniRoute/              # Root package
├── src/                # Next.js 16 app (TypeScript)
├── open-sse/           # @omniroute/open-sse workspace (streaming engine)
├── electron/           # Desktop app (Electron)
├── tests/              # All test suites
├── docs/               # Documentation
└── bin/                # CLI entry point

---

Request Pipeline (Abbreviated)

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

---

Key Conventions

Code Style

• 2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas
• Imports: external → internal (@/, @omniroute/open-sse) → relative
• Naming: files=camelCase/kebab, components=PascalCase, constants=UPPER_SNAKE

Database Access

• Always go through src/lib/db/ domain modules
• Never write raw SQL in routes or handlers
• Never add logic to src/lib/localDb.ts (re-export layer only)
• Never barrel-import from localDb.ts — import specific db/ modules
• DB singleton: getDbInstance() from src/lib/db/core.ts (WAL journaling)
• Migrations: src/lib/db/migrations/ — 21 versioned SQL files

Error Handling

• try/catch with specific error types, log with pino context
• Never swallow errors in SSE streams — use abort signals
• Return proper HTTP status codes (4xx/5xx)

Security

• Never commit secrets/credentials
• Never use eval(), new Function(), or implied eval
• Validate all inputs with Zod schemas
• Encrypt credentials at rest (AES-256-GCM)

---

Common Modification Scenarios

Adding a New Provider

1. Register in src/shared/constants/providers.ts (Zod-validated at load)
2. Add executor in open-sse/executors/ if custom logic needed
3. Add translator in open-sse/translator/ if non-OpenAI format
4. Add OAuth config in src/lib/oauth/constants/oauth.ts if OAuth-based
5. Register models in open-sse/config/providerRegistry.ts
6. Write tests in tests/unit/ (registration, translation, error handling)

Adding a New API Route

1. Create directory under src/app/api/v1/your-route/
2. Create route.ts with GET/POST handlers
3. Follow pattern: CORS → Zod body validation → optional auth → handler delegation
4. Handler goes in open-sse/handlers/ (import from there, not inline)
5. Add tests

Adding a New DB Module

1. Create src/lib/db/yourModule.ts
2. Import getDbInstance from ./core.ts
3. Export CRUD functions for your domain table(s)
4. Add migration in src/lib/db/migrations/ if new tables needed
5. Re-export from src/lib/localDb.ts (add to the re-export list only)
6. Write tests

Adding a New MCP Tool

1. Add tool definition in open-sse/mcp-server/tools/
2. Define Zod input schema + async handler
3. Register in tool set (wired by createMcpServer())
4. Assign to appropriate scope(s)
5. Write tests (tool invocation logged to mcp_audit table)

Adding a New A2A Skill

1. Create skill in src/lib/a2a/skills/
2. Skill receives task context (messages, metadata) → returns structured result
3. Register in the DB-backed skill registry
4. Write tests

---

Testing Cheat Sheet

What	Command
All tests	npm run test:all
Unit tests	npm run test:unit
Single file	node --import tsx/esm --test tests/unit/file.test.mjs
Vitest (MCP, autoCombo)	npm run test:vitest
E2E (Playwright)	npm run test:e2e
Protocol E2E (MCP+A2A)	npm run test:protocols:e2e
Ecosystem	npm run test:ecosystem
Coverage gate	npm run test:coverage (60% min all metrics)
Coverage report	npm run coverage:report

PR rule: If you change production code in src/, open-sse/, electron/, or bin/, you must include or update tests in the same PR.

---

Git Workflow

# Never commit directly to main
git checkout -b feat/your-feature
# ... make changes ...
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: add circuit breaker for provider calls
fix: resolve JWT secret validation edge case
docs: update AGENTS.md with pipeline internals
test: add MCP tool unit tests
refactor(db): consolidate rate limit tables

Scopes: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills.

---

Environment

• Runtime: Node.js ≥18 <24, ES Modules
• TypeScript: 5.9, target ES2022, module esnext, resolution bundler
• Path aliases: @/* → src/, @omniroute/open-sse → open-sse/
• Default port: 20128 (API + dashboard on same port)
• Data directory: DATA_DIR env var, defaults to ~/.omniroute/
• Key env vars: PORT, JWT_SECRET, INITIAL_PASSWORD, REQUIRE_API_KEY, APP_LOG_LEVEL

---

Hard Rules (Never Violate)

1. Never commit secrets or credentials
2. Never add logic to localDb.ts
3. Never use eval() / new Function() / implied eval
4. Never commit directly to main
5. Never write raw SQL in routes — use src/lib/db/ modules
6. Never silently swallow errors in SSE streams
7. Always validate inputs with Zod schemas
8. Always include tests when changing production code
9. Coverage must stay ≥60% (statements, lines, functions, branches)