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
TypeScript a2aai-agentsai-gatewayanthropicclaudeclaude-codeclinecodexcopilotcursordeepseekfree-aigeminikimillm-gatewaymcpopenaiopenai-proxyqwentoken-saver
feat: CLI Integration Suite for issue #2016
oyi772d601ea4592b
diff --git a/@omniroute/opencode-provider/README.md b/@omniroute/opencode-provider/README.mdnew file mode 100644index 0000000000..33689031a1--- /dev/null+++ b/@omniroute/opencode-provider/README.md@@ -0,0 +1,45 @@+# @omniroute/opencode-provider++Provider plugin for connecting [OpenCode](https://github.com/anomalyco/opencode) to [OmniRoute](https://github.com/diegosouzapw/OmniRoute).++## Installation++```bash+npm install @omniroute/opencode-provider+```++## Usage++```javascript+import { createOmniRouteProvider } from "@omniroute/opencode-provider";++const provider = createOmniRouteProvider({+ baseURL: "http://localhost:20128/v1",+ apiKey: "your-omniroute-api-key",+});+```++Then configure OpenCode to use the provider:++```jsonc+// OpenCode settings+{+ "provider": provider+}+```++## API++### `createOmniRouteProvider(options)`++Creates an OpenCode-compatible provider object that routes requests through OmniRoute.++**Options:**++| Option | Type | Required | Description |+| --------- | -------- | -------- | ---------------------------------------------------------- |+| `baseURL` | `string` | Yes | OmniRoute API base URL (e.g., `http://localhost:20128/v1`) |+| `apiKey` | `string` | Yes | OmniRoute API key |+| `model` | `string` | No | Model identifier (default: `"opencode"`) |++**Returns:** An OpenCode-compatible provider object with `id`, `name`, `npm`, `options`, and `auth` fields.diff --git a/@omniroute/opencode-provider/index.d.ts b/@omniroute/opencode-provider/index.d.tsnew file mode 100644index 0000000000..32b235cb9e--- /dev/null+++ b/@omniroute/opencode-provider/index.d.ts@@ -0,0 +1,3 @@+import OmniRouteProvider from "./index.js";+export { OmniRouteProvider };+export default OmniRouteProvider;diff --git a/@omniroute/opencode-provider/index.js b/@omniroute/opencode-provider/index.jsnew file mode 100644index 0000000000..3fb4f441d1--- /dev/null+++ b/@omniroute/opencode-provider/index.js@@ -0,0 +1 @@+export { createOmniRouteProvider, default as default } from "./index.ts";diff --git a/@omniroute/opencode-provider/index.ts b/@omniroute/opencode-provider/index.tsnew file mode 100644index 0000000000..e053e65c65--- /dev/null+++ b/@omniroute/opencode-provider/index.ts@@ -0,0 +1,54 @@+/**+ * OpenCode provider plugin for OmniRoute AI Gateway+ *+ * Usage:+ * import { createOmniRouteProvider } from "@omniroute/opencode-provider";+ * const provider = createOmniRouteProvider({+ * baseURL: "http://localhost:20128/v1",+ * apiKey: "your-api-key",+ * });+ *+ * Then add to OpenCode settings:+ * { "provider": provider }+ */++export interface OmniRouteProviderOptions {+ baseURL: string;+ apiKey: string;+ model?: string;+}++export interface OmniRouteProvider {+ id: string;+ name: string;+ npm: string;+ options: Record<string, unknown>;+ auth: { type: string; apiKey: string };+}++export function createOmniRouteProvider(options: OmniRouteProviderOptions): OmniRouteProvider {+ if (!options.baseURL) {+ throw new Error("baseURL is required");+ }+ if (!options.apiKey) {+ throw new Error("apiKey is required");+ }++ const baseURL = options.baseURL.replace(/\/+$/, "");++ return {+ id: "omniroute",+ name: "OmniRoute AI Gateway",+ npm: "@omniroute/opencode-provider",+ options: {+ baseURL: `${baseURL}/v1`,+ model: options.model || "opencode",+ },+ auth: {+ type: "apiKey",+ apiKey: options.apiKey,+ },+ };+}++export default createOmniRouteProvider;diff --git a/@omniroute/opencode-provider/package.json b/@omniroute/opencode-provider/package.jsonnew file mode 100644index 0000000000..4ffc071ca2--- /dev/null+++ b/@omniroute/opencode-provider/package.json@@ -0,0 +1,20 @@+{+ "name": "@omniroute/opencode-provider",+ "version": "1.0.0",+ "description": "OpenCode provider plugin for OmniRoute AI Gateway",+ "type": "module",+ "main": "index.js",+ "types": "index.d.ts",+ "files": [+ "index.js",+ "index.d.ts",+ "README.md"+ ],+ "keywords": [+ "omniroute",+ "opencode",+ "provider"+ ],+ "license": "MIT",+ "peerDependencies": {}+}diff --git a/README.md b/README.mdindex 5ea1659691..501c21dc6a 100644--- a/README.md+++ b/README.md@@ -1,493 +1,1549 @@-<!-- SEO Meta Tags -->-<meta name="description" content="Unified AI proxy/router with 177+ providers, Auto-Combo intelligent routing, RTK+Caveman compression (15-95% savings), MCP server (37 tools), A2A protocol, and auto-fallback to FREE & low-cost AI models.">-<meta name="keywords" content="AI gateway, LLM router, OpenAI proxy, Anthropic proxy, multi-provider AI, free AI API, prompt compression, token optimization, ChatGPT alternative, Claude API gateway, OmniRoute, Auto-Combo, MCP server, A2A protocol">--<!-- OpenGraph -->-<meta property="og:type" content="website">-<meta property="og:title" content="OmniRoute — The Free AI Gateway">-<meta property="og:description" content="One endpoint, 177+ providers, 14 routing strategies, auto-fallback to free models. RTK+Caveman compression saves 15-95% tokens.">-<meta property="og:url" content="https://github.com/diegosouzapw/OmniRoute">-<meta property="og:image" content="https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/docs/screenshots/MainOmniRoute.png">-<meta property="og:site_name" content="OmniRoute">--<!-- Twitter Card -->-<meta name="twitter:card" content="summary_large_image">-<meta name="twitter:title" content="OmniRoute — The Free AI Gateway">-<meta name="twitter:description" content="One endpoint, 177+ providers, auto-fallback to FREE models. Open-source. Self-hosted. MIT.">-<meta name="twitter:image" content="https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/docs/screenshots/MainOmniRoute.png">--<!-- JSON-LD Schema -->-<script type="application/ld+json">-{- "@context": "https://schema.org",- "@type": "SoftwareApplication",- "name": "OmniRoute",- "applicationCategory": "DeveloperApplication",- "operatingSystem": "Windows, macOS, Linux, Android (Termux)",- "offers": { "@type": "Offer", "price": "0", "priceCurrency": "USD" },- "description": "Unified AI proxy/router with 177+ providers, Auto-Combo 9-factor routing, RTK+Caveman compression, MCP/A2A protocols, and auto-fallback to FREE models.",- "url": "https://github.com/diegosouzapw/OmniRoute",- "softwareVersion": "3.8.0",- "author": { "@type": "Person", "name": "Diego Souza" },- "license": "https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE",- "downloadUrl": "https://www.npmjs.com/package/omniroute",- "features": [- "177+ AI providers",- "Auto-Combo zero-config routing",- "RTK + Caveman prompt compression",- "Auto-fallback with circuit breaker",- "MCP Server (37 tools, 3 transports)",- "A2A Protocol (v0.3, 5 skills)",- "Cloud Agents (Codex Cloud, Devin, Jules)",- "Memory + Skills + Webhooks + Guardrails",- "30+ language UI translations",- "Desktop (Electron 41) + PWA + Termux"- ]-}-</script>-<div align="center">-# 🚀 OmniRoute+# 🚀 OmniRoute — The Free AI Gateway++### Never stop coding. Save 15-95% eligible tokens with RTK+Caveman compression + auto-fallback to **FREE & low-cost AI models**.++_The most complete open-source AI proxy — **one endpoint**, **160+ providers**, **13 routing strategies**, zero downtime. Multi-platform: **Web**, **Desktop (Electron)**, **Mobile (PWA + Termux)**. Fully extensible via **MCP Server (37 tools)**, **A2A Protocol**, and **Memory/Skills** systems. Available in **40+ languages**._-### **The Free AI Gateway — one endpoint, 177+ providers, zero downtime.**+**Chat Completions • Responses API • Embeddings • Image Generation • Video • Music • Audio Speech/Transcription • Reranking • Moderations • Web Search • MCP Server • A2A Protocol • 4,600+ Tests • 100% TypeScript**-**Auto-fallback to free models. Stop coding interruptions. Cut tokens 15-95%.**+<br/>-[](https://www.npmjs.com/package/omniroute)-[](LICENSE)-[](package.json)-[](https://github.com/diegosouzapw/OmniRoute)-[](https://trendshift.io/repositories/23589)+<a href="https://agentrouter.org/register?aff=70LM">+ <img src="https://img.shields.io/badge/🎁_GET_$100_FREE_AI_CREDITS-AgentRouter_(no_card_needed)-ff6600?style=for-the-badge&labelColor=1a1a2e&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xMiAyTDIgNy41bDEwIDUuNSAxMC01LjVMMTIgMnpNMiAxNy41bDEwIDUuNSAxMC01LjVMMTIgMTIgMiAxNy41eiIvPjwvc3ZnPg==" alt="Get $100 Free AI Credits" height="40"/>+</a>-[**Website**](https://omniroute.online) · [**Quick Start**](#-quick-start) · [**Docs**](#-documentation) · [**Discord/WhatsApp**](#-community)+<sub>🔥 <b>Limited offer:</b> Sign up at <a href="https://agentrouter.org/register?aff=70LM"><b>AgentRouter</b></a> and get <b>$100 in free AI credits</b></br> Access GPT-5, Claude, Gemini, DeepSeek & 100+ models. No credit card required. <a href="https://agentrouter.org/register?aff=70LM"><b>Claim your credits →</b></a></sub>-<sub>v3.8.0 · MIT · Production-ready · Self-hosted</sub>+<br/>++<a href="https://trendshift.io/repositories/23589" target="_blank"><img src="https://trendshift.io/api/badge/repositories/23589" alt="diegosouzapw%2FOmniRoute | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>++[🚀 Quick Start](#-quick-start) • [💡 Features](#-key-features) • [🗜️ Compression](#%EF%B8%8F-prompt-compression--save-15-95-eligible-tokens-automatically) • [💰 Pricing](#-pricing-at-a-glance) • [🎯 Use Cases](#-use-cases--ready-made-combo-playbooks) • [🌍 Proxy](#-bypass-geographic-blocks--use-ai-from-any-country) • [❓ FAQ](#-frequently-asked-questions) • [📖 Docs](#-documentation) • [💬 WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)</div>----## ⚡ The Pitch (60 seconds)+<div align="">++🌐 **Available in:** 🇺🇸 [English](README.md) | 🇧🇷 [Português (Brasil)](docs/i18n/pt-BR/README.md) | 🇪🇸 [Español](docs/i18n/es/README.md) | 🇫🇷 [Français](docs/i18n/fr/README.md) | 🇮🇹 [Italiano](docs/i18n/it/README.md) | 🇷🇺 [Русский](docs/i18n/ru/README.md) | 🇨🇳 [中文 (简体)](docs/i18n/zh-CN/README.md) | 🇩🇪 [Deutsch](docs/i18n/de/README.md) | 🇮🇳 [हिन्दी](docs/i18n/in/README.md) | 🇹🇭 [ไทย](docs/i18n/th/README.md) | 🇺🇦 [Українська](docs/i18n/uk-UA/README.md) | 🇸🇦 [العربية](docs/i18n/ar/README.md) | 🇯🇵 [日本語](docs/i18n/ja/README.md) | 🇻🇳 [Tiếng Việt](docs/i18n/vi/README.md) | 🇧🇬 [Български](docs/i18n/bg/README.md) | 🇩🇰 [Dansk](docs/i18n/da/README.md) | 🇫🇮 [Suomi](docs/i18n/fi/README.md) | 🇮🇱 [עברית](docs/i18n/he/README.md) | 🇭🇺 [Magyar](docs/i18n/hu/README.md) | 🇮🇩 [Bahasa Indonesia](docs/i18n/id/README.md) | 🇰🇷 [한국어](docs/i18n/ko/README.md) | 🇲🇾 [Bahasa Melayu](docs/i18n/ms/README.md) | 🇳🇱 [Nederlands](docs/i18n/nl/README.md) | 🇳🇴 [Norsk](docs/i18n/no/README.md) | 🇵🇹 [Português (Portugal)](docs/i18n/pt/README.md) | 🇷🇴 [Română](docs/i18n/ro/README.md) | 🇵🇱 [Polski](docs/i18n/pl/README.md) | 🇸🇰 [Slovenčina](docs/i18n/sk/README.md) | 🇸🇪 [Svenska](docs/i18n/sv/README.md) | 🇵🇭 [Filipino](docs/i18n/phi/README.md) | 🇨🇿 [Čeština](docs/i18n/cs/README.md)++</div>++<div align="center">++[](https://www.npmjs.com/package/omniroute)+++++[](https://hub.docker.com/r/diegosouzapw/omniroute)+++[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)++<!-- Community & Social -->-| 🎯 The problem | ✅ How OmniRoute solves it |-| ------------------------------ | -------------------------------------------------------------------------------------------------- |-| Hit rate limits on Claude/GPT? | **Auto-fallback** across 177 providers — never see a 429 again |-| Bored of switching API keys? | **One endpoint** (`localhost:20128`) speaks OpenAI, Anthropic, Gemini, Claude Code, Cursor formats |-| Paying $200/mo for AI? | **11 free providers** + intelligent routing → most users pay $0 |-| Tokens too expensive? | **RTK + Caveman compression** saves 15-95% on eligible payloads |-| Blocked region? | **4-level proxy** (account/provider/combo/global) + **1proxy free marketplace** |-| Want CLI agents free? | Plug **Cursor, Cline, Codex, Claude Code, Aider, 15+ CLIs** at OmniRoute |+[](https://github.com/diegosouzapw)+[](https://github.com/diegosouzapw)+[](https://omniroute.online)+[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)-📺 **Watch in action:** [Video demo](https://www.youtube.com/@diegosouza-pw)+</div>----## 🖼️ Dashboard Preview+## 🖼️ Main Dashboard-+<div align="center">+ <img src="./docs/screenshots/MainOmniRoute.png" alt="OmniRoute Dashboard" width="800"/>+</div>-<details>-<summary><b>Click for more screenshots</b> (Providers, Combos, Memory, MCP, Audit…)</summary>+----| | |-| --------------------------------------------- | ---------------------------------------------------- |-|  |  |-|  |  |-|  |  |+## 📸 Dashboard Preview++<details>+<summary><b>Click to see dashboard screenshots</b></summary>++| Page | Screenshot |+| -------------- | ------------------------------------------------- |+| **Providers** |  |+| **Combos** |  |+| **Analytics** |  |+| **Health** |  |+| **Translator** |  |+| **Settings** |  |+| **CLI Tools** |  |+| **Usage Logs** |  |+| **Endpoints** |  |</details>----## ⚡ Quick Start+### 🤖 Free AI Provider for your favorite coding agents++_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._++ <table>+ <tr>+ <td align="center" width="110">+ <a href="https://github.com/openclaw/openclaw">+ <img src="./public/providers/openclaw.png" alt="OpenClaw" width="48"/><br/>+ <b>OpenClaw</b>+ </a><br/>+ <sub>⭐ 205K</sub>+ </td>+ <td align="center" width="110">+ <a href="https://github.com/HKUDS/nanobot">+ <img src="./public/providers/nanobot.png" alt="NanoBot" width="48"/><br/>+ <b>NanoBot</b>+ </a><br/>+ <sub>⭐ 20.9K</sub>+ </td>+ <td align="center" width="110">+ <a href="https://github.com/sipeed/picoclaw">+ <img src="./public/providers/picoclaw.jpg" alt="PicoClaw" width="48"/><br/>+ <b>PicoClaw</b>+ </a><br/>+ <sub>⭐ 14.6K</sub>+ </td>+ <td align="center" width="110">+ <a href="https://github.com/zeroclaw-labs/zeroclaw">+ <img src="./public/providers/zeroclaw.png" alt="ZeroClaw" width="48"/><br/>+ <b>ZeroClaw</b>+ </a><br/>+ <sub>⭐ 9.9K</sub>+ </td>+ <td align="center" width="110">+ <a href="https://github.com/nearai/ironclaw">+ <img src="./public/providers/ironclaw.png" alt="IronClaw" width="48"/><br/>+ <b>IronClaw</b>+ </a><br/>+ <sub>⭐ 2.1K</sub>+ </td>+ </tr>+ <tr>+ <td align="center" width="110">+ <a href="https://github.com/anomalyco/opencode">+ <img src="./public/providers/opencode.svg" alt="OpenCode" width="48"/><br/>+ <b>OpenCode</b>+ </a><br/>+ <sub>⭐ 106K</sub>+ </td>+ <td align="center" width="110">+ <a href="https://github.com/openai/codex">+ <img src="./public/providers/codex.svg" alt="Codex CLI" width="48"/><br/>+ <b>Codex CLI</b>+ </a><br/>+ <sub>⭐ 60.8K</sub>+ </td>+ <td align="center" width="110">+ <a href="https://github.com/anthropics/claude-code">+ <img src="./public/providers/claude.svg" alt="Claude Code" width="48"/><br/>+ <b>Claude Code</b>+ </a><br/>+ <sub>⭐ 67.3K</sub>+ </td>+ <td align="center" width="110">+ <a href="https://github.com/google-gemini/gemini-cli">+ <img src="./public/providers/gemini-cli.svg" alt="Gemini CLI" width="48"/><br/>+ <b>Gemini CLI</b>+ </a><br/>+ <sub>⭐ 94.7K</sub>+ </td>+ <td align="center" width="110">+ <a href="https://github.com/Kilo-Org/kilocode">+ <img src="./public/providers/kilocode.svg" alt="Kilo Code" width="48"/><br/>+ <b>Kilo Code</b>+ </a><br/>+ <sub>⭐ 15.5K</sub>+ </td>+ </tr>+ </table>++<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>-```bash-# Run instantly (npx — no install needed)-npx -y omniroute@latest+----# Or install globally-npm install -g omniroute && omniroute+## 📺 OmniRoute in Action — Video Guides-# Or via Docker-docker run -d -p 20128:20128 diegosouzapw/omniroute:3.8.0-```+<div align="center">++<table>+ <tr>+ <td align="center" width="320">+ <a href="https://www.youtube.com/watch?v=Rxdc36yUyOQ">+ <img src="https://img.youtube.com/vi/Rxdc36yUyOQ/maxresdefault.jpg" alt="OmniRoute — Guia em Português" width="300"/>+ </a><br/>+ <b>🇧🇷 Português</b><br/>+ <sub>Guia completo do OmniRoute</sub>+ </td>+ <td align="center" width="320">+ <a href="https://www.youtube.com/watch?v=CMzyOiUyEVc">+ <img src="https://img.youtube.com/vi/CMzyOiUyEVc/maxresdefault.jpg" alt="OmniRoute — English Guide" width="300"/>+ </a><br/>+ <b>🇺🇸 English</b><br/>+ <sub>Complete OmniRoute walkthrough</sub>+ </td>+ <td align="center" width="320">+ <a href="https://www.youtube.com/watch?v=il_5Ii6v4-Y">+ <img src="https://img.youtube.com/vi/il_5Ii6v4-Y/maxresdefault.jpg" alt="OmniRoute — Руководство на русском" width="300"/>+ </a><br/>+ <b>🇷🇺 Русский</b><br/>+ <sub>Полное руководство по OmniRoute</sub>+ </td>+ </tr>+</table>++</div>++> 🎬 **Made a video about OmniRoute?** We'd love to feature it here! Open an [issue](https://github.com/diegosouzapw/OmniRoute/issues/new) or [discussion](https://github.com/diegosouzapw/OmniRoute/discussions) with the link and we'll add it to this showcase.++---++## 🤔 Why OmniRoute?++**Stop wasting money, tokens and hitting limits:**++❌ Subscription quota expires unused every month+❌ Rate limits stop you mid-coding+❌ Tool outputs (`git diff`, `grep`, `ls`...) burn tokens fast+❌ Expensive APIs ($20-50/month per provider)+❌ Manual switching between providers+❌ Each provider has a different API format+❌ AI providers blocked in your country++**OmniRoute solves all of this:**++✅ **Prompt Compression** — auto-compress prompts & tool outputs, save 15-95% eligible tokens per request with RTK+Caveman stacked mode+✅ **Maximize subscriptions** — track quota, use every bit before reset+✅ **Auto fallback** — Subscription → API Key → Cheap → Free, zero downtime+✅ **Multi-account** — round-robin between accounts per provider+✅ **Format translation** — OpenAI ↔ Claude ↔ Gemini ↔ Responses API, any tool works+✅ **3-level proxy** — bypass geo-blocks with global, per-provider, and per-key proxies+✅ **10 multi-modal APIs** — chat, images, video, music, audio, search in one endpoint+✅ **MCP + A2A** — 29 MCP tools + agent-to-agent protocol, production-ready+✅ **Universal** — works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool-→ Open **http://localhost:20128** → login with `admin` / `CHANGEME` → connect your first provider via OAuth or API key.+---++## 📧 Support++> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.++- **Website**: [omniroute.online](https://omniroute.online)+- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)+- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)++### 🐛 Reporting a Bug?-**Point any OpenAI-compatible client at OmniRoute:**+When opening an issue, please run the system-info command and attach the generated file:```bash-export OPENAI_BASE_URL=http://localhost:20128/v1-export OPENAI_API_KEY=or_<your-omniroute-key>+npm run system-info```-That's it. Cursor, Cline, Codex, Continue, Aider, and any SDK now work. → Detailed setup: [`docs/guides/SETUP_GUIDE.md`](docs/guides/SETUP_GUIDE.md)+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.----## 🌟 What's new in v3.8.0+## 🛠️ Supported CLI Tools++OmniRoute works seamlessly with **16+ AI coding tools** — one config, all tools:++<table>+ <tr>+ <td align="center" width="110"><b>Claude Code</b><br/><sub>Anthropic</sub></td>+ <td align="center" width="110"><b>Codex CLI</b><br/><sub>OpenAI</sub></td>+ <td align="center" width="110"><b>Gemini CLI</b><br/><sub>Google</sub></td>+ <td align="center" width="110"><b>Cursor</b><br/><sub>IDE</sub></td>+ <td align="center" width="110"><b>OpenClaw</b><br/><sub>CLI</sub></td>+ <td align="center" width="110"><b>Antigravity</b><br/><sub>VS Code</sub></td>+ </tr>+ <tr>+ <td align="center" width="110"><b>Cline</b><br/><sub>Extension</sub></td>+ <td align="center" width="110"><b>Continue</b><br/><sub>Extension</sub></td>+ <td align="center" width="110"><b>Kilo Code</b><br/><sub>Extension</sub></td>+ <td align="center" width="110"><b>Kiro</b><br/><sub>AWS IDE</sub></td>+ <td align="center" width="110"><b>OpenCode</b><br/><sub>CLI</sub></td>+ <td align="center" width="110"><b>Droid</b><br/><sub>CLI</sub></td>+ </tr>+ <tr>+ <td align="center" width="110"><b>AMP</b><br/><sub>CLI</sub></td>+ <td align="center" width="110"><b>Copilot</b><br/><sub>GitHub</sub></td>+ <td align="center" width="110"><b>Windsurf</b><br/><sub>IDE</sub></td>+ <td align="center" width="110"><b>Hermes</b><br/><sub>CLI</sub></td>+ <td align="center" width="110"><b>Qwen CLI</b><br/><sub>Alibaba</sub></td>+ <td align="center" width="110"><b>Custom</b><br/><sub>Any tool</sub></td>+ </tr>+</table>++📖 Full setup for each tool: [`docs/CLI-TOOLS.md`](docs/CLI-TOOLS.md)++---++## 🌐 Supported Providers — 160+++### 🔐 OAuth Providers++<table>+ <tr>+ <td align="center" width="130"><b>Claude Code</b><br/><sub>Anthropic OAuth</sub></td>+ <td align="center" width="130"><b>Antigravity</b><br/><sub>Google OAuth</sub></td>+ <td align="center" width="130"><b>Codex</b><br/><sub>OpenAI OAuth</sub></td>+ <td align="center" width="130"><b>GitHub Copilot</b><br/><sub>GitHub OAuth</sub></td>+ <td align="center" width="130"><b>Cursor</b><br/><sub>Cursor OAuth</sub></td>+ </tr>+ <tr>+ <td align="center" width="130"><b>Kimi Coding</b><br/><sub>Moonshot OAuth</sub></td>+ <td align="center" width="130"><b>Kilo Code</b><br/><sub>Kilo OAuth</sub></td>+ <td align="center" width="130"><b>Cline</b><br/><sub>Cline OAuth</sub></td>+ <td align="center" colspan="2"></td>+ </tr>+</table>++### 🆓 Free Providers (No Cost)++<table>+ <tr>+ <td align="center" width="160"><b>🟢 Kiro AI</b><br/><sub>Claude Sonnet/Haiku<br/>Unlimited FREE</sub></td>+ <td align="center" width="160"><b>🟢 Qoder AI</b><br/><sub>Kimi-K2, DeepSeek-R1<br/>Unlimited FREE</sub></td>+ <td align="center" width="160"><b>🟢 Pollinations</b><br/><sub>GPT-5, Claude, Llama 4<br/>No API key needed</sub></td>+ <td align="center" width="160"><b>🟢 Qwen Code</b><br/><sub>Qwen3 Coder Plus<br/>Unlimited FREE</sub></td>+ </tr>+ <tr>+ <td align="center" width="160"><b>🟢 LongCat AI</b><br/><sub>Flash-Lite<br/>50M tokens/day</sub></td>+ <td align="center" width="160"><b>🟢 Cloudflare AI</b><br/><sub>50+ models<br/>10K neurons/day</sub></td>+ <td align="center" width="160"><b>🟢 Puter AI</b><br/><sub>GPT-4.1, Claude<br/>Rate-limited free</sub></td>+ <td align="center" width="160"><b>🟢 NVIDIA NIM</b><br/><sub>Llama, Mistral<br/>1K req/day free</sub></td>+ </tr>+</table>++### 🔑 API Key Providers (120+)++<table>+ <tr>+ <td align="center" width="110"><b>OpenAI</b></td>+ <td align="center" width="110"><b>Anthropic</b></td>+ <td align="center" width="110"><b>Gemini</b></td>+ <td align="center" width="110"><b>DeepSeek</b></td>+ <td align="center" width="110"><b>Groq</b></td>+ <td align="center" width="110"><b>xAI (Grok)</b></td>+ </tr>+ <tr>+ <td align="center" width="110"><b>Mistral</b></td>+ <td align="center" width="110"><b>OpenRouter</b></td>+ <td align="center" width="110"><b>GLM</b></td>+ <td align="center" width="110"><b>Kimi</b></td>+ <td align="center" width="110"><b>MiniMax</b></td>+ <td align="center" width="110"><b>Fireworks</b></td>+ </tr>+ <tr>+ <td align="center" width="110"><b>Together AI</b></td>+ <td align="center" width="110"><b>Cerebras</b></td>+ <td align="center" width="110"><b>Cohere</b></td>+ <td align="center" width="110"><b>NVIDIA</b></td>+ <td align="center" width="110"><b>Perplexity</b></td>+ <td align="center" width="110"><b>SiliconFlow</b></td>+ </tr>+ <tr>+ <td align="center" width="110"><b>Nebius</b></td>+ <td align="center" width="110"><b>HuggingFace</b></td>+ <td align="center" width="110"><b>DeepInfra</b></td>+ <td align="center" width="110"><b>SambaNova</b></td>+ <td align="center" width="110"><b>Vertex AI</b></td>+ <td align="center" width="110"><b>Azure OpenAI</b></td>+ </tr>+ <tr>+ <td align="center" width="110"><b>AWS Bedrock</b></td>+ <td align="center" width="110"><b>Snowflake</b></td>+ <td align="center" width="110"><b>Databricks</b></td>+ <td align="center" width="110"><b>Venice.ai</b></td>+ <td align="center" width="110"><b>AI21 Labs</b></td>+ <td align="center" width="110"><b>Meta Llama</b></td>+ </tr>+</table>++<details>+<summary><b>...and 90+ more providers</b></summary>++Alibaba · Amazon Q · AssemblyAI · Baidu Qianfan · Baseten · Black Forest Labs · Blackbox · Brave Search · Bytez · CablyAI · Cartesia · ChatGPT Web · Chutes.ai · Clarifai · Codestral · CrofAI · DataRobot · Deepgram · ElevenLabs · Empower · Exa Search · Fal.ai · Featherless AI · FenayAI · FriendliAI · Galadriel · GigaChat · GitLab Duo · GLHF Chat · GoAPI · Heroku AI · Hyperbolic · IBM watsonx · Inference.net · Inworld · Jina AI · Kilo Gateway · Lambda AI · LaoZhang · Linkup Search · LlamaGate · Maritalk · Modal · Moonshot AI · Morph · Muse Spark · NanoBanana · NanoGPT · NLP Cloud · Nous Research · Novita AI · nScale · OCI · Ollama Cloud · OVHcloud · PiAPI · PlayHT · Poe · Predibase · PublicAI · Qwen Code · Recraft · Reka · Runway · SAP · Scaleway · SearchAPI · SearXNG · Serper · Stability AI · Synthetic · Tavily · TheB.AI · Topaz · Upstage · v0 (Vercel) · Vercel AI Gateway · Volcengine · Voyage AI · W&B Inference · Xiaomi MiMo · You.com · Z.AI · + OpenAI/Anthropic-compatible custom endpoints++</details>++### 🏠 Self-Hosted++<table>+ <tr>+ <td align="center" width="130"><b>LM Studio</b></td>+ <td align="center" width="130"><b>Ollama</b></td>+ <td align="center" width="130"><b>vLLM</b></td>+ <td align="center" width="130"><b>Llamafile</b></td>+ <td align="center" width="130"><b>Docker Model Runner</b></td>+ </tr>+ <tr>+ <td align="center" width="130"><b>NVIDIA Triton</b></td>+ <td align="center" width="130"><b>XInference</b></td>+ <td align="center" width="130"><b>oobabooga</b></td>+ <td align="center" width="130"><b>ComfyUI</b></td>+ <td align="center" width="130"><b>SD WebUI</b></td>+ </tr>+</table>++----- 🤖 **Auto-Combo zero-config routing** — just use `auto/coding`, `auto/cheap`, `auto/fast`, `auto/offline`, `auto/smart`, `auto/lkgp` as model IDs-- 🎯 **Manifest-aware tier routing W1-W4** — automatic tier prioritization-- 🆕 **Command Code provider** + **Z.AI quota labels** + **KIE video expansion**-- 🔐 **Windsurf + Devin CLI + GitLab Duo OAuth** flows-- 🆓 **9 new free providers**: LLM7, Lepton, Kluster, UncloseAI, BazaarLink, Completions, Enally, FreeTheAi, AgentRouter ($200 credits)-- 🩺 **Model Cooldowns dashboard** with manual re-enable-- 🎨 **Cursor full OpenAI parity** (tools, streaming, sessions)-- 📌 **Per-session sticky routing** for Codex-- 🔊 **Inworld TTS** enhancements-- 🧠 **Reasoning Replay Cache** — fixes 400s on DeepSeek V4, Kimi K2, Qwen-Thinking, GLM-- 🔄 **Reset-aware routing** strategy (14th strategy)-- 🛠️ **20+ new CLI commands** (`omniroute setup/doctor/providers/combos`)+## 🔄 How It Works-→ Full changelog: [`CHANGELOG.md`](CHANGELOG.md)+```+┌─────────────┐+│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)+│ Tool │+└──────┬──────┘+ │ http://localhost:20128/v1+ ↓+┌──────────────────────────────────────────────────┐+│ OmniRoute (Smart Router) │+│ • 🗜️ Prompt Compression (save 15-95% eligible) │+│ • Format translation (OpenAI ↔ Claude ↔ Gemini) │+│ • Quota tracking + Embeddings + Images │+│ • Auto token refresh + Rate limit management │+└──────┬───────────────────────────────────────────┘+ │+ ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI+ │ ↓ quota exhausted+ ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.+ │ ↓ budget limit+ ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)+ │ ↓ budget limit+ └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)++Result: Never stop coding, minimal cost + 15-95% eligible token savings+```----## 🎯 Why OmniRoute Wins+## 🗜️ Prompt Compression — Save 15-95% Eligible Tokens Automatically++> **Why use many token when few token do trick?** OmniRoute's built-in compression pipeline reduces token usage before requests reach the provider. It combines ideas from [RTK - Rust Token Killer](https://github.com/rtk-ai/rtk) and [Caveman](https://github.com/JuliusBrussee/caveman) (⭐ 51K+).++### How It Works++Every request passes through the compression pipeline **transparently** — no client changes needed:++```+┌──────────────────┐ ┌─────────────────────────────┐ ┌──────────────┐+│ Client sends │────▶│ OmniRoute Compression │────▶│ Provider │+│ full prompt │ │ Pipeline (7 options) │ │ receives │+│ (10,000 tok) │ │ │ │ compressed │+│ │ │ 🪶 Lite ........... ~15% │ │ (~1,080 tok)│+│ │ │ 🪨 Standard ....... ~30% │ │ │+│ │ │ ⚡ Aggressive ..... ~50% │ │ 💰 up to 95%│+│ │ │ 🔥 Ultra .......... ~75% │ │ │+│ │ │ 🧰 RTK ............ 60-90% │ │ │+│ │ │ 🔗 Stacked ........ 78-95% │ │ │+└──────────────────┘ └─────────────────────────────┘ └──────────────┘+```++### 7 Compression Options++| Mode | Savings | Technique | Best For |+| ------------------------- | ------- | ----------------------------------------------------------------------------------------------- | -------------------------------------- |+| **Off** | 0% | No compression | When you need exact prompts |+| **🪶 Lite** | ~15% | Whitespace collapse, dedup system prompts, image URL shortening | Always-on safe default |+| **🪨 Standard (Caveman)** | ~30% | 30+ regex rules: filler removal, context condensation, structural compression, multi-turn dedup | Daily coding with Claude/Codex |+| **⚡ Aggressive** | ~50% | All standard + progressive message aging + tool result summarization + LLM-based compression | Long sessions with many tool calls |+| **🔥 Ultra** | ~75% | All aggressive + heuristic token pruning + stopword removal + score-based filtering | Maximum savings when tokens are scarce |+| **🧰 RTK** | 60-90% | 49 command-aware filters, RTK-style JSON DSL, verify gate, trust-gated custom filters | Shell/test/build/git output in agents |+| **🔗 Stacked** | 78-95% | RTK first, then Caveman input condensation; ~89% with upstream average math | Mixed prompts with tool logs + prose |++### RTK + Caveman Savings Math++These numbers are based on the upstream project READMEs under `_references/_outros`:++| Source | Upstream claim used by OmniRoute docs |+| ------- | ------------------------------------------------------------------------------------------------------------------- |+| Caveman | `~75%` fewer output tokens; benchmark average `65%` output savings, range `22-87%`; `~46%` input compression tool |+| RTK | `60-90%` command-output token savings; sample session `~118,000 -> ~23,900` tokens, which is `79.7%` saved (`~80%`) |++For the default stacked compression combo, OmniRoute runs:++```txt+RTK -> Caveman+```++When both engines can act on the same tool/context payload, the savings compound:++```txt+combined = 1 - (1 - RTK savings) * (1 - Caveman input savings)+average = 1 - (1 - 0.80) * (1 - 0.46) = 89.2%+range = 1 - (1 - 0.60..0.90) * (1 - 0.46) = 78.4-94.6%+```++Caveman output mode is separate from prompt compression. When enabled for responses, use Caveman's+own upstream output numbers: `65%` average, `~75%` headline, `22-87%` observed range. Total bill+savings depend on the prompt/output mix, but coding-agent sessions are often tool-context heavy, so+the `RTK -> Caveman` combo is the best default for maximum context savings.++### Before & After (Standard/Caveman Mode)++**🗣️ Before compression (69 tokens):**++> "The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I would recommend using useMemo to memoize the object."-| | OmniRoute v3.8 | LiteLLM | OpenRouter |-| ------------------ | ------------------- | ---------------- | ------------- |-| Providers | **177+** | ~50 | ~50 |-| Free providers | **11** | 0 | 0 |-| OAuth providers | **14** | 0 | 1 |-| Routing strategies | **14** | 3 | 1 |-| Auto routing | ✅ 9-factor scoring | ❌ | ❌ |-| Prompt compression | ✅ RTK + Caveman | ❌ | ❌ |-| MCP server | ✅ 37 tools | ❌ | ❌ |-| A2A protocol | ✅ v0.3 + 5 skills | ❌ | ❌ |-| Desktop app | ✅ Electron 41 | ❌ | ❌ |-| PWA | ✅ | ❌ | ❌ |-| Self-hosted | ✅ MIT | Limited | ❌ (cloud) |-| Pricing | **$0 forever** | OSS / Cloud paid | 10% fee + API |+**🪨 After compression (19 tokens):**-→ Detailed comparison: [`docs/guides/FEATURES.md`](docs/guides/FEATURES.md)+> "New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."++**Same answer. 72% less tokens. Zero accuracy loss.**++### Architecture++```+Request Body+ │+ ├─ strategySelector.ts ─── Picks mode (config / combo override / auto-trigger)+ │+ ├─ lite.ts ─────────────── Whitespace, dedup, image URLs, redundant content+ ├─ caveman.ts ──────────── 30+ regex rules via cavemanRules.ts+ │ └─ preservation.ts ─── Protects code blocks, URLs, JSON from compression+ ├─ engines/rtk/ ────────── Command detection + JSON DSL filters + raw-output recovery+ ├─ engines/registry.ts ─── Shared engine registry for caveman, RTK, and stacked+ ├─ aggressive.ts ───────── Summarizer + tool result compressor + progressive aging+ │ ├─ summarizer.ts ───── Rule-based message summarization+ │ ├─ toolResultCompressor.ts ── file/grep/shell/JSON/error compression+ │ └─ progressiveAging.ts ──── Older messages → shorter summaries+ └─ ultra.ts ────────────── Heuristic token scoring + pruning+ └─ ultraHeuristic.ts ─ Stopword detection, score thresholds, force-preserve+```++### Configuration++```+Dashboard → Context & Cache → Caveman / RTK / Compression Combos+```++Or per-combo override:++```json+{+ "comboOverrides": {+ "my-coding-combo": "standard",+ "my-cheap-combo": "ultra"+ }+}+```++Auto-trigger: set `autoTriggerTokens` to automatically enable compression when a request exceeds a token threshold.++Compression combos can also assign a named compression pipeline to routing combos, so a coding combo can use RTK + Caveman while a paid subscription combo stays on lite mode.++> 🪨 **Fun fact:** The standard/caveman mode is inspired by [Caveman](https://github.com/JuliusBrussee/caveman) — the viral project that reports 65% average output-token savings while keeping technical accuracy. OmniRoute takes this further with a **7-option pipeline** and a default `RTK -> Caveman` combo that can reach ~89% average savings on eligible tool/context payloads.++📖 **Full compression documentation:** [`docs/COMPRESSION_GUIDE.md`](docs/COMPRESSION_GUIDE.md) • [`docs/RTK_COMPRESSION.md`](docs/RTK_COMPRESSION.md) • [`docs/COMPRESSION_ENGINES.md`](docs/COMPRESSION_ENGINES.md) • [`docs/COMPRESSION_RULES_FORMAT.md`](docs/COMPRESSION_RULES_FORMAT.md) • [`docs/COMPRESSION_LANGUAGE_PACKS.md`](docs/COMPRESSION_LANGUAGE_PACKS.md)----## 🛠️ Compatible CLI Tools (17+)+## 🎯 What OmniRoute Solves-All work out-of-the-box once you point `OPENAI_BASE_URL` at OmniRoute:+> **Every developer using AI tools faces these problems daily.** OmniRoute solves them all.-**Claude family:** Claude Code · Cline · Continue · Kilo Code · Kimi Coding-**OpenAI family:** Codex CLI · Cursor · Aider · OpenClaw · Droid · AMP-**Google family:** Gemini CLI · Antigravity · Jules-**Others:** Windsurf · GitLab Duo · Devin CLI · Hermes · Amazon Q · Kiro · Qoder · Custom+| # | Problem | OmniRoute Solution |+| --- | ---------------------------------------- | ----------------------------------------------------------------------------------------------- |+| 💸 | Subscription quota expires mid-coding | **Smart 4-Tier Fallback** — auto-routes Subscription → API Key → Cheap → Free |+| 🔌 | Each provider has a different API format | **Format Translation** — unified endpoint translates OpenAI ↔ Claude ↔ Gemini ↔ Responses |+| 🌐 | AI providers block my country/region | **3-Level Proxy** — global, per-provider, and per-key proxy with TLS fingerprint spoofing |+| 🆓 | Can't afford AI subscriptions | **11 Free Providers** — Kiro, Qoder, Pollinations, LongCat, Cloudflare AI, NVIDIA NIM... |+| 🔒 | Gateway is exposed without protection | **API Key Management** — scoping, rotation, IP filtering, rate limiting, prompt injection guard |+| 🛑 | Provider went down, lost coding flow | **Circuit Breakers** — auto-failover with cooldown, retry, anti-thundering herd |+| 🔧 | Configuring each CLI tool is tedious | **CLI Tools Dashboard** — one-click setup for Claude Code, Codex, Cursor, OpenClaw, Kilo |+| 🔑 | Managing OAuth tokens is hell | **Auto Token Refresh** — OAuth PKCE for 8 providers, multi-account, LAN/remote fix |+| 📊 | Don't know how much I'm spending | **Cost Analytics** — per-token tracking, budget limits, usage stats per API key |+| 🐛 | Can't diagnose errors in AI calls | **Unified Logs** — 4-tab dashboard (request, proxy, audit, console) + p50/p95/p99 telemetry |-→ Full setup: [`docs/reference/CLI-TOOLS.md`](docs/reference/CLI-TOOLS.md)+<details>+<summary><b>📖 See all 31 problems OmniRoute solves</b></summary>++| # | Problem | Solution |+| --- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- |+| 11 | Deploying/maintaining is complex | npm global, Docker multi-arch, Electron, Termux — deploy anywhere |+| 12 | Interface is English-only | 40+ languages with RTL support |+| 13 | Need more than chat (images, audio, video) | 10 multi-modal APIs: embeddings, images, video, music, TTS, STT, moderation, rerank, search, batch |+| 14 | No way to test/compare models | LLM Evals, Translator Playground, Chat Tester, Live Monitor |+| 15 | Need to scale without losing performance | Semantic cache, request dedup, rate limit detection, queue & pacing |+| 16 | Want to control model behavior globally | System prompt injection, thinking budget, wildcard routing |+| 17 | Need MCP tools as first-class features | 29 MCP tools, 3 transports (stdio/SSE/HTTP), 10 scopes, audit trail |+| 18 | Need A2A orchestration | JSON-RPC 2.0 + SSE streaming, task lifecycle, sync + stream paths |+| 19 | Need real MCP process health | Runtime heartbeat, PID tracking, UI status cards |+| 20 | Need auditable MCP execution | SQLite-backed audit with filters, pagination, stats |+| 21 | Need scoped MCP permissions | 10 granular scopes per integration |+| 22 | Need operational controls without redeploying | Combo switches, resilience tuning, breaker resets from dashboard |+| 23 | Need A2A task lifecycle visibility | Task listing/filtering, drill-down, cancellation |+| 24 | Need active stream metrics | Active stream counters, per-state counts, A2A dashboard cards |+| 25 | Need standard agent discovery | Agent Card at `/.well-known/agent.json` |+| 26 | Need protocol discoverability | Consolidated Endpoints page with Proxy, MCP, A2A, API tabs |+| 27 | Need E2E protocol validation | Real MCP SDK + A2A client flows in `test:protocols:e2e` |+| 28 | Need unified observability | Health + audit + telemetry across OpenAI, MCP, and A2A layers |+| 29 | Need one runtime for proxy + tools + agents | OpenAI proxy + MCP + A2A in one stack with shared auth/resilience |+| 30 | Need agentic workflows without glue-code | Unified endpoint, protocol UIs, production-ready foundations |+| 31 | Long sessions crash with context limits | Proactive context compression, structural integrity guards, multi-layer dropping |++</details>++📖 **Deep dives:** [Resilience Guide](docs/RESILIENCE_GUIDE.md) • [Proxy Guide](docs/PROXY_GUIDE.md) • [Setup Guide](docs/SETUP_GUIDE.md) • [Compression Guide](docs/COMPRESSION_GUIDE.md)----## 🌐 Providers (177+)+## 🆓 Start Free — Zero Configuration Cost++> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.++| Step | Action | Providers Unlocked |+| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |+| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |+| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |+| 5 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |++**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.-### 🆓 Free providers (11 — no API key or unlimited tier)+> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).-| Provider | Highlight |-| --------------------------------------------------- | --------------------------------------- |-| **Kiro AI** | 50 credits/month (Claude Sonnet/Haiku) |-| **Qoder AI** | Unlimited (Kimi-K2, Qwen3, DeepSeek-R1) |-| **Gemini CLI** | 180K tokens/month |-| **Amazon Q** | AWS Builder ID OAuth |-| **LongCat** | 50M tokens/day |-| **Pollinations** | No API key, GPT-5 + Claude |-| **AgentRouter** | $200 free credits |-| **LLM7** · **Lepton** · **Kluster** · **UncloseAI** | New v3.8 free tiers |+## ⚡ Quick Start-⚠️ Qwen Code OAuth was **discontinued on 2026-04-15** (use API key with `alicode` provider instead).+### 1) Install and run-→ Curated guide: [`docs/reference/FREE_TIERS.md`](docs/reference/FREE_TIERS.md) · Full catalog: [`docs/reference/PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md) (auto-generated)+```bash+npm install -g omniroute+omniroute+```-### 🔐 OAuth providers (14)+Dashboard opens at `http://localhost:20128` · API at `http://localhost:20128/v1`.-Claude Code · Codex · GitHub Copilot · Cursor · Antigravity · Gemini · Kimi Coding · Kilo Code · Cline · Qwen · Kiro · Qoder · Windsurf · GitLab Duo+### 2) Connect providers-### 🔑 API key providers (~123)+1. Dashboard → **Providers** → connect at least one provider (OAuth or API key)+2. Dashboard → **Endpoints** → create an API key+3. Dashboard → **Combos** → set your fallback chain (optional)-OpenAI · Anthropic · Google · Mistral · Cohere · DeepSeek · Groq · Together · Fireworks · Cerebras · SambaNova · NVIDIA NIM · Bedrock · Vertex · Azure · Cloudflare AI · 100+ more.+### 3) Point your coding tool++```txt+Base URL: http://localhost:20128/v1+API Key: [copy from Endpoint page]+Model: if/kimi-k2-thinking (or any provider/model)+```-### 🏠 Self-hosted (10)+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and any OpenAI-compatible tool.-Ollama · LM Studio · vLLM · Llamafile · Lemonade · Petals · Triton · Docker Model Runner · Xinference · Oobabooga+<details>+<summary><b>📦 More install methods (Docker, source, Arch, Void, pnpm)</b></summary>++**Docker:**++```bash+docker run -d --name omniroute --restart unless-stopped -p 20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest+```++**From source:**++```bash+cp .env.example .env && npm install+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev+```++**pnpm:** `pnpm install -g omniroute && pnpm approve-builds -g && omniroute`++**Arch Linux (AUR):** `yay -S omniroute-bin && systemctl --user enable --now omniroute.service`++**MCP:** `omniroute --mcp` (stdio transport)++**CLI options:** `omniroute setup`, `omniroute doctor`, `omniroute providers available`, `omniroute providers list`, `omniroute --port 3000`, `omniroute --no-open`, `omniroute --help`++**Split-port mode:** `PORT=20128 DASHBOARD_PORT=20129 omniroute`++**Uninstall:** `npm run uninstall` (keeps data) or `npm run uninstall:full` (removes everything)++📖 Full details: [Setup Guide](#-setup-guide) · [Docker](#-docker) · [Void Linux template](#-quick-start)++</details>----## 🤖 Auto-Combo — Zero-Config Routing+## 🐳 Docker++OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).-Just use `auto/<variant>` as model ID. No combo setup needed.+**Quick run:**```bash-# 6 variants + plain `auto`:-auto/coding # → optimized for coding tasks-auto/cheap # → minimize cost-auto/fast # → minimize latency-auto/offline # → prefer local providers-auto/smart # → prefer top-tier models-auto/lkgp # → Last-Known-Good-Path (sticky)-auto # → balanced default+docker run -d \+ --name omniroute \+ --restart unless-stopped \+ --stop-timeout 40 \+ -p 20128:20128 \+ -v omniroute-data:/app/data \+ diegosouzapw/omniroute:latest+```++**With environment file:**++```bash+# Copy and edit .env first+cp .env.example .env++docker run -d \+ --name omniroute \+ --restart unless-stopped \+ --stop-timeout 40 \+ --env-file .env \+ -p 20128:20128 \+ -v omniroute-data:/app/data \+ diegosouzapw/omniroute:latest+```++**Using Docker Compose:**++```bash+# Base profile (no CLI tools)+docker compose --profile base up -d++# CLI profile (Claude Code, Codex, OpenClaw built-in)+docker compose --profile cli up -d```-**How it picks:** 9-factor scoring (health · quota · cost · latency · taskFit · stability · tierPriority · tierAffinity · specificityMatch) over a virtual candidate pool built from all enabled providers.+Dashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL. Endpoint tunnel panels, including Cloudflare, Tailscale, and ngrok, can be shown or hidden from `Settings → Appearance` without changing active tunnel state.++Notes:++- Quick Tunnel URLs are temporary and change after every restart.+- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.+- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.+- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.+- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.+- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.+- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.++**Using Docker Compose with Caddy (HTTPS Auto-TLS):**++OmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.++```yaml+services:+ omniroute:+ image: diegosouzapw/omniroute:latest+ container_name: omniroute+ restart: unless-stopped+ volumes:+ - omniroute-data:/app/data+ environment:+ - PORT=20128+ - NEXT_PUBLIC_BASE_URL=https://your-domain.com++ caddy:+ image: caddy:latest+ container_name: caddy+ restart: unless-stopped+ ports:+ - "80:80"+ - "443:443"+ command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128++volumes:+ omniroute-data:+```++| Image | Tag | Size | Description |+| ------------------------ | -------- | ------ | --------------------- |+| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |+| `diegosouzapw/omniroute` | `3.7.8` | ~250MB | Current version |-→ Full guide: [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md)+📖 **Full Docker documentation:** [`docs/DOCKER_GUIDE.md`](docs/DOCKER_GUIDE.md) — Compose profiles, Caddy HTTPS, Cloudflare tunnels, and more.----## 🗜️ Prompt Compression — Save 15-95% Tokens+## 📱 Multi-Platform — Run Anywhere++> OmniRoute runs on **Web**, **Desktop (Electron)**, **Android (Termux)**, and as a **Progressive Web App (PWA)**.-Two engines, stackable:+| Platform | Install | Highlights |+| -------------- | -------------------------------------------- | -------------------------------------------------------------------------- |+| 🖥️ **Desktop** | `npm run electron:build` | Native window, system tray, auto-start, offline mode — Windows/macOS/Linux |+| 📱 **Android** | `pkg install nodejs-lts && npx -y omniroute` | ARM native, no root, 24/7 via Termux:Boot — your phone is an AI server |+| 📲 **PWA** | "Add to Home Screen" in browser | Fullscreen, offline page, service worker caching — Android/iOS/Desktop |++<details>+<summary><b>🖥️ Desktop App details</b></summary>-- **Caveman** — natural-language condensation (filler removal, hedging, repeated context). 30+ regex rules per language pack (en, es, pt-BR, de, fr, ja).-- **RTK** — terminal/shell/git/test output. 49 declarative filters.+- Native Electron app with system tray, auto-start, native notifications+- One-click install: NSIS (Windows), DMG (macOS), AppImage (Linux)+- Dev: `npm run electron:dev` · Build: `npm run electron:build`+- 📖 Full docs: [`electron/README.md`](electron/README.md)-**Modes:** `off` · `lite` · `standard` · `aggressive` · `ultra` · `rtk` · `stacked` (RTK→Caveman, max savings).+</details>-→ [`docs/compression/COMPRESSION_GUIDE.md`](docs/compression/COMPRESSION_GUIDE.md) · [`docs/compression/RTK_COMPRESSION.md`](docs/compression/RTK_COMPRESSION.md) · [`docs/compression/COMPRESSION_LANGUAGE_PACKS.md`](docs/compression/COMPRESSION_LANGUAGE_PACKS.md)+<details>+<summary><b>📱 Android (Termux) details</b></summary>++```bash+pkg update && pkg install nodejs-lts python build-essential git+npx -y omniroute@latest+```++Access from any device on the same network: `http://PHONE_IP:20128/v1`++- 📖 Full guide: [`docs/TERMUX_GUIDE.md`](docs/TERMUX_GUIDE.md)++</details>++<details>+<summary><b>📲 PWA details</b></summary>++- **Android (Chrome):** ⋮ → "Add to Home screen"+- **iOS (Safari):** Share → "Add to Home Screen"+- **Desktop (Chrome/Edge):** Install icon in address bar+- 📖 Full docs: [`docs/PWA_GUIDE.md`](docs/PWA_GUIDE.md)++</details>----## 🌍 Bypass Geographic Blocks+## 🌍 Bypass Geographic Blocks — Use AI From Any Country++> 🇷🇺 🇨🇳 🇮🇷 🇨🇺 🇹🇷 **In Russia, China, Iran, or any blocked region?** OmniRoute's 3-level proxy system solves this completely.++| Level | Badge | Configure In | Use Case |+| ------------------ | ----- | ------------------ | ------------------------------- |+| **Global** | 🟢 | Settings → Proxy | All traffic through one proxy |+| **Per-Provider** | 🟡 | Provider → Proxy | Only specific providers proxied |+| **Per-Connection** | 🔵 | Connection → Proxy | Each API key uses its own proxy |++**What gets proxied:** API requests ✅ • OAuth flows ✅ • Connection tests ✅ • Token refresh ✅ • Model sync ✅++**Protocols:** HTTP/HTTPS, SOCKS5 (`ENABLE_SOCKS5_PROXY=true`), Authenticated proxies-For users in **Russia, China, Iran, Cuba, Turkey** and other regions:+### 🆓 1proxy — Free Proxy Marketplace-- **4-level outbound proxy** — account / provider / combo / global scopes-- **1proxy free marketplace** — auto-syncs working HTTP/SOCKS5 proxies-- **Anti-detection** — TLS fingerprinting (JA3/JA4), CCH headshakes, header sanitization-- **Public tunnels** — Cloudflare (Quick or Named), ngrok, Tailscale Funnel for OAuth callbacks+> Contributed by [@oyi77](https://github.com/oyi77) — [#1847](https://github.com/diegosouzapw/OmniRoute/pull/1847)-→ [`docs/ops/PROXY_GUIDE.md`](docs/ops/PROXY_GUIDE.md) · [`docs/ops/TUNNELS_GUIDE.md`](docs/ops/TUNNELS_GUIDE.md) · [`docs/security/STEALTH_GUIDE.md`](docs/security/STEALTH_GUIDE.md)+No proxy? Use the built-in **1proxy** integration for **hundreds of free, validated proxies** worldwide:++- One-click sync (up to 500 proxies) • Quality scores (0-100) • Country filter • Auto-rotation (quality/random/sequential) • Auto-degradation • Circuit breaker++### Anti-Detection++- 🔒 **TLS Fingerprint Spoofing** — browser-like TLS via `wreq-js`+- 🔏 **CLI Fingerprint Matching** — matches native CLI binary signatures+- 🏠 **Proxy IP Preservation** — stealth + IP masking simultaneously++📖 **Full proxy documentation:** [`docs/PROXY_GUIDE.md`](docs/PROXY_GUIDE.md)----## 📱 Multi-Platform+----| Platform | Install | Doc |-| --------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------- |-| **CLI / Server** | `npm install -g omniroute` | [`SETUP_GUIDE.md`](docs/guides/SETUP_GUIDE.md) |-| **Desktop (Win/Mac/Linux)** | Electron installer from GitHub Releases | [`ELECTRON_GUIDE.md`](docs/guides/ELECTRON_GUIDE.md) |-| **PWA** | Install from any modern browser | [`PWA_GUIDE.md`](docs/guides/PWA_GUIDE.md) |-| **Android (Termux)** | `pkg install nodejs-lts && npm i -g omniroute` | [`TERMUX_GUIDE.md`](docs/guides/TERMUX_GUIDE.md) |-| **Docker** | `docker compose up` (base/cli/host/cliproxyapi profiles) | [`DOCKER_GUIDE.md`](docs/guides/DOCKER_GUIDE.md) |-| **VM / VPS** | Generic Ubuntu/Debian + nginx + systemd | [`VM_DEPLOYMENT_GUIDE.md`](docs/ops/VM_DEPLOYMENT_GUIDE.md) |-| **Fly.io** | `fly deploy` | [`FLY_IO_DEPLOYMENT_GUIDE.md`](docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) |+## 💰 Pricing at a Glance++| Tier | Provider | Cost | Quota Reset | Best For |+| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |+| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |+| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |+| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |+| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |+| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |+| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |+| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |+| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |+| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |+| | Mistral | Free trial + paid | Rate limited | European AI |+| | OpenRouter | Pay-per-use | None | 100+ models aggr. |+| | AgentRouter 🆕 | Pay-per-use | None | $200 free credits at signup |+| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |+| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |+| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |+| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |+| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |+| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |+| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |+| | Qwen | **$0** | Unlimited | 4 models unlimited |+| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |+| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |+| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |+| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |+| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |++> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.++**💡 See the full [$0 Free Stack (11 providers)](#-free-models--11-providers-0-forever) below.**++> 💡 **Understanding Dashboard Costs:**+>+> The "cost" displayed in the Usage Analytics page is **for tracking and comparison purposes only**.+> OmniRoute itself **never charges you anything** — it's free, open-source software running on your machine.+> If your dashboard shows "$290 total cost" while using free models, that's how much you **saved** compared to paid API pricing.+> Think of it as a **savings tracker**, not a bill.----## 🧩 Extensibility+## 🆓 Free Models — 11 Providers, $0 Forever++> Combine all free providers into one unbreakable combo — OmniRoute auto-routes between them when quota runs out.++| Provider | Prefix | Free Models | Quota |+| ----------------- | ----------- | ------------------------------------------------------------- | -------------------- |+| **Kiro** | `kr/` | Claude Sonnet 4.5, Haiku 4.5, Opus 4.6 | 50 CREDITS per month |+| **Qoder** | `if/` | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2.1 | ♾️ Unlimited |+| **Qwen** | `qw/` | qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next | ♾️ Unlimited |+| **Pollinations** | `pol/` | GPT-5, Claude, Gemini, DeepSeek, Llama 4, Mistral | No key needed |+| **LongCat** | `lc/` | LongCat-Flash-Lite | 50M tokens/day 🔥 |+| **Gemini CLI** | `gc/` | gemini-3-flash, gemini-2.5-pro | 180K tok/mo |+| **Cloudflare AI** | `cf/` | 50+ models (Llama, Gemma, Mistral, Whisper) | 10K Neurons/day |+| **Groq** | `groq/` | Llama 3.3 70B, Qwen3 32B, Kimi K2 | 14.4K RPD |+| **NVIDIA NIM** | `nvidia/` | 129 models (DeepSeek, Llama, GLM, Kimi) | ~40 RPM |+| **Cerebras** | `cerebras/` | Qwen3 235B, GPT-OSS 120B, Llama 3.1 | 1M tok/day |+| **Scaleway** | `scw/` | Qwen3 235B, Llama 70B, DeepSeek V3 | 1M tokens (EU) |++<details>+<summary><b>📖 25+ more free providers — Groq, Cerebras, Mistral, GitHub Models, OpenRouter, and more</b></summary>++**Also free (API Key required):**+Mistral (1B tok/month) · OpenRouter (35+ `:free` models) · GitHub Models (GPT-5, 45+ models) ·+Cohere (1K calls/month) · Z.AI/GLM (permanent free Flash models) · SiliconFlow (1K RPM, 50K TPM) ·+Kilo Code (~200 req/hr auto-router) · HuggingFace ($0.10/mo credits) · Ollama Cloud (400+ models) ·+LLM7.io (30+ models) · Kluster AI · IBM watsonx (300K tok/month) · OpenCode Zen · Vercel AI Gateway ($5/mo)++**Trial credits (one-time):**+Baseten ($30) · NLP Cloud ($15) · AI21 ($10) · Upstage ($10) · SambaNova ($5) · Modal ($5/mo) ·+Fireworks ($1) · Nebius ($1) · Inference.net ($1 + $25 survey) · Hyperbolic ($1) · Novita ($0.50)++**China-based (free tiers):**+ModelScope · Tencent Hunyuan · Volcengine · ChatAnywhere · InternAI · Bigmodel++**Combined capacity: ~31,000+ RPD · ~32B+ tokens/month · 500+ models · $0**++</details>-| System | What it does | Docs |-| ----------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------ |-| 🧠 **Skills** | Built-in skills + marketplace + sandboxed custom skills (Docker) | [`docs/frameworks/SKILLS.md`](docs/frameworks/SKILLS.md) |-| 💾 **Memory** | Persistent conversational memory (SQLite FTS5 + Qdrant vector) | [`docs/frameworks/MEMORY.md`](docs/frameworks/MEMORY.md) |-| ☁️ **Cloud Agents** | Submit long tasks to Codex Cloud / Devin / Jules | [`docs/frameworks/CLOUD_AGENT.md`](docs/frameworks/CLOUD_AGENT.md) |-| 🪝 **Webhooks** | HMAC-signed event delivery (request.completed, quota.exceeded, etc.) | [`docs/frameworks/WEBHOOKS.md`](docs/frameworks/WEBHOOKS.md) |-| 🛡️ **Guardrails** | PII masker, prompt injection guard, vision bridge — hot-reload | [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md) |-| 🧪 **Evals** | Suite-based regression testing (combos/models/cases/rubrics) | [`docs/frameworks/EVALS.md`](docs/frameworks/EVALS.md) |-| 🔍 **Compliance/Audit** | `audit_log` table, retention, `noLog` opt-out, SSRF logging | [`docs/security/COMPLIANCE.md`](docs/security/COMPLIANCE.md) |-| 🛡️ **MCP Server** | 37 tools, 3 transports (stdio/SSE/Streamable HTTP), ~13 scopes | [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md) |-| 🤝 **A2A Protocol** | v0.3 JSON-RPC, 5 skills (smart-routing, quota, discovery, cost, health) | [`docs/frameworks/A2A-SERVER.md`](docs/frameworks/A2A-SERVER.md) |+📖 **Complete free provider directory:** [`docs/FREE_TIERS.md`](docs/FREE_TIERS.md) — 25+ providers, quotas, base URLs, model tables, and OmniRoute combo setup.----## 📚 Documentation+## 🎙️ Free Transcription Combo-Everything you need, organized by area.+> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.-### 🚀 Start here+| Provider | Free Credits | Best Model | Rate Limit |+| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |+| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |+| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |+| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |-- [`SETUP_GUIDE.md`](docs/guides/SETUP_GUIDE.md) — install + connect first provider-- [`USER_GUIDE.md`](docs/guides/USER_GUIDE.md) — end-user manual (modes, combos, CLIs, audio, ~1200 lines)-- [`FREE_TIERS.md`](docs/reference/FREE_TIERS.md) — start free, no card-- [`TROUBLESHOOTING.md`](docs/guides/TROUBLESHOOTING.md) — common issues + v3.8 known issues+----### 🏛️ Architecture+**Suggested combo in `/dashboard/combos`:**-- [`ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md) — high-level architecture-- [`CODEBASE_DOCUMENTATION.md`](docs/architecture/CODEBASE_DOCUMENTATION.md) — engineering reference-- [`REPOSITORY_MAP.md`](docs/architecture/REPOSITORY_MAP.md) — every directory and root file-- [`FEATURES.md`](docs/guides/FEATURES.md) — full feature matrix+```+Name: free-transcription+Strategy: Priority+Nodes:+ [1] deepgram/nova-3 → uses $200 free first+ [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out+ [3] groq/whisper-large-v3 → free forever, emergency fallback+```-### 🔌 API & contracts+Then in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.-- [`API_REFERENCE.md`](docs/reference/API_REFERENCE.md) — endpoint reference-- [`openapi.yaml`](docs/reference/openapi.yaml) — OpenAPI 3.0 spec-- [`PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md) — full catalog (auto-generated)-- [`CLI-TOOLS.md`](docs/reference/CLI-TOOLS.md) — CLI integrations + internal CLI-- [`ENVIRONMENT.md`](docs/reference/ENVIRONMENT.md) — all env vars+## 💡 Key Features-### 🎯 Routing & resilience+> **4,690+ automated tests** across 517 test files. Not just a relay — a full operational platform.-- [`AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md) — Auto-Combo (9-factor scoring, 14 strategies)-- [`RESILIENCE_GUIDE.md`](docs/architecture/RESILIENCE_GUIDE.md) — circuit breaker + cooldown + lockout-- [`REASONING_REPLAY.md`](docs/routing/REASONING_REPLAY.md) — reasoning cache for DeepSeek/Kimi/Qwen-- [`STEALTH_GUIDE.md`](docs/security/STEALTH_GUIDE.md) — TLS fingerprinting + obfuscation+| Feature | Why It Matters |+| ---------------------------------------------------------------------------------------------------- | -------------------------------- |+| 🧠 **Smart 4-Tier Fallback** — Subscription → API → Cheap → Free | Never stop coding, zero downtime |+| 🔄 **Format Translation** — OpenAI ↔ Claude ↔ Gemini ↔ Responses API | Works with ANY CLI tool |+| 🗜️ **Prompt Compression** — 7 options including Caveman, RTK, and stacked pipelines | Save 15-95% eligible tokens |+| 🤖 **MCP Server** — 37 tools, 3 transports (stdio/SSE/HTTP), 10 scopes | IDE/agent tool integration |+| 🛡️ **Resilience Engine** — circuit breakers, cooldowns, TLS spoofing, anti-thundering herd | Auto-recovery from any failure |+| 🎵 **10 Multi-Modal APIs** — chat, embed, images, video, music, TTS, STT, moderation, rerank, search | One endpoint for everything |+| 🌍 **3-Level Proxy** — global, per-provider, per-key + 1proxy free marketplace | Access AI from any country |+| 📊 **Full Observability** — unified logs, p50/p95/p99 telemetry, cost tracking, budget controls | Know exactly what's happening |-### 🤖 Agent protocols+<details>+<summary><b>📋 Complete feature list — 30+ capabilities</b></summary>-- [`AGENT_PROTOCOLS_GUIDE.md`](docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) — A2A vs ACP vs Cloud Agents-- [`MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md) — Model Context Protocol server-- [`A2A-SERVER.md`](docs/frameworks/A2A-SERVER.md) — Agent-to-Agent protocol-- [`CLOUD_AGENT.md`](docs/frameworks/CLOUD_AGENT.md) — Codex Cloud / Devin / Jules+**Routing & Intelligence**-### 🧠 Extensions+- 13 balancing strategies (priority, weighted, round-robin, P2C, cost-optimized, context-relay...)+- Task-aware smart routing (coding/vision/analysis) · Context relay session handoffs+- Thinking budget controls (passthrough/auto/custom) · Wildcard routing · System prompt injection-- [`SKILLS.md`](docs/frameworks/SKILLS.md) — Skills framework-- [`MEMORY.md`](docs/frameworks/MEMORY.md) — Memory system-- [`EVALS.md`](docs/frameworks/EVALS.md) — Eval framework-- [`GUARDRAILS.md`](docs/security/GUARDRAILS.md) — PII / injection / vision-- [`WEBHOOKS.md`](docs/frameworks/WEBHOOKS.md) — Webhook delivery-- [`COMPLIANCE.md`](docs/security/COMPLIANCE.md) — Audit + retention-- [`AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md) — Authorization pipeline+**Translation & Compatibility**-### 🗜️ Compression+- Auto token refresh (OAuth PKCE for 8 providers) · Multi-account round-robin+- Responses API — full `/v1/responses` for Codex · Batch API with Files API+- OpenAPI 3.0 live spec + Try-It UI-- [`COMPRESSION_GUIDE.md`](docs/compression/COMPRESSION_GUIDE.md)-- [`COMPRESSION_ENGINES.md`](docs/compression/COMPRESSION_ENGINES.md)-- [`COMPRESSION_RULES_FORMAT.md`](docs/compression/COMPRESSION_RULES_FORMAT.md)-- [`COMPRESSION_LANGUAGE_PACKS.md`](docs/compression/COMPRESSION_LANGUAGE_PACKS.md)-- [`RTK_COMPRESSION.md`](docs/compression/RTK_COMPRESSION.md)+**Protocols**-### 🚀 Deployment+- A2A Server — JSON-RPC 2.0, SSE streaming, task lifecycle, skills+- ACP — CLI agent discovery (14 agents + custom)-- [`DOCKER_GUIDE.md`](docs/guides/DOCKER_GUIDE.md)-- [`VM_DEPLOYMENT_GUIDE.md`](docs/ops/VM_DEPLOYMENT_GUIDE.md)-- [`FLY_IO_DEPLOYMENT_GUIDE.md`](docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md)-- [`ELECTRON_GUIDE.md`](docs/guides/ELECTRON_GUIDE.md)-- [`PWA_GUIDE.md`](docs/guides/PWA_GUIDE.md)-- [`TERMUX_GUIDE.md`](docs/guides/TERMUX_GUIDE.md)-- [`TUNNELS_GUIDE.md`](docs/ops/TUNNELS_GUIDE.md)-- [`PROXY_GUIDE.md`](docs/ops/PROXY_GUIDE.md)+**Platform**-### 📋 Operations+- Desktop (Electron) · Android (Termux) · PWA · Docker (AMD64 + ARM64)+- Cloudflare / Tailscale / ngrok tunnels · 40+ languages with RTL+- Semantic + signature cache (two-tier) · Request idempotency + deduplication-- [`RELEASE_CHECKLIST.md`](docs/ops/RELEASE_CHECKLIST.md) — release flow with Claude Code skills-- [`COVERAGE_PLAN.md`](docs/ops/COVERAGE_PLAN.md) — test coverage state (current: 82.58%/82.58%/84.23%/75.22%)-- [`I18N.md`](docs/guides/I18N.md) — 30 supported locales-- [`UNINSTALL.md`](docs/guides/UNINSTALL.md)+**Observability**-### 🤝 Contributing & policy+- Health dashboard — uptime, breakers, cache, lockouts+- Evaluation framework — golden set testing · Webhooks · Compliance audit-- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contributor guide-- [`SECURITY.md`](SECURITY.md) — security policy-- [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)-- [`CLAUDE.md`](CLAUDE.md) — rules for Claude Code agents-- [`AGENTS.md`](AGENTS.md) — rules for non-Claude agents-- [`GEMINI.md`](GEMINI.md) — rules for Gemini agents+**v3.6+ Highlights:**+V1 WebSocket Bridge · Sync Tokens & Config Bundle · GLM Thinking (glmt) · Hybrid Token Counting ·+Safe Outbound Fetch · Wait For Cooldown · Runtime Env Validation · Vision Bridge ·+Grok-4 Fast · GLM-5 via Z.AI · MiniMax M2.5 · toolCalling flag ·+Multilingual Intent Detection · Benchmark-Driven Fallbacks · Request Deduplication----+**Architecture Examples:**-## 💡 Use Cases+```txt+Combo: "my-coding-stack" Format Translation:+ 1. cc/claude-opus-4-7 CLI → OpenAI format+ 2. nvidia/llama-3.3-70b OmniRoute → translates+ 3. glm/glm-4.7 Provider → native format+ 4. if/kimi-k2-thinking+```-| Scenario | Solution |-| --------------------------------- | ------------------------------------------------------------- |-| "Claude Pro user, hit rate limit" | Combo: Claude → GLM → DeepSeek (auto-fallback) |-| "Want $0 forever" | `auto/cheap` → Kiro/Qoder/Pollinations fallback chain |-| "24/7 coding, no interruptions" | `auto/lkgp` (sticky to last-good) + Resilience |-| "Blocked region" | 1proxy free marketplace + Cloudflare Quick Tunnel |-| "Max token savings" | Stacked compression: `rtk → caveman` (78-95% on logs) |-| "Multi-agent system" | Expose OmniRoute as A2A node, route via `smart-routing` skill |-| "Long-running coding task" | Cloud Agents → Devin/Jules with management auth |+📖 [MCP Server README](open-sse/mcp-server/README.md) · [A2A Server README](src/lib/a2a/README.md) · [Resilience Guide](docs/RESILIENCE_GUIDE.md) · [Features Gallery](docs/FEATURES.md)-→ Detailed playbooks: [`USER_GUIDE.md`](docs/guides/USER_GUIDE.md) · [`AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md)+</details>----## 📡 Protocols supported+## 🎯 Use Cases — Ready-Made Combo Playbooks++### Case 0: "I want zero-config, auto-routing NOW"-OmniRoute speaks all major AI protocols — clients don't need to change:+**Problem:** Don't want to create combos manually. Just want AI routing to work immediately.-- **OpenAI** (Chat Completions, Responses, Embeddings, Images, Audio, Files, Batches, Rerank, Moderations)-- **Anthropic Messages** (Claude format, with thinking blocks + reasoning replay)-- **Google Gemini** (generateContent + Vertex)-- **Claude Code** (CLI-specific format with CCH + fingerprinting)-- **Cursor** (proprietary format with tool calls)-- **Kiro** (AWS Builder ID OAuth)-- **MCP** (Model Context Protocol — 37 tools, stdio/SSE/Streamable HTTP)-- **A2A** (Agent-to-Agent v0.3 JSON-RPC — agent card at `/.well-known/agent.json`)+```bash+# No combo creation needed! Use auto/ prefix directly:+model: "auto" # Default LKGP routing across all connected providers+model: "auto/coding" # Quality-first weights for code generation+model: "auto/fast" # Low-latency routing (fastest provider first)+model: "auto/cheap" # Cost-optimized (cheapest per token)+model: "auto/offline" # High availability (most quota available)+model: "auto/smart" # Best discovery (10% exploration rate)+```++**How it works:**++1. Add providers in Dashboard → Providers (OAuth or API key)+2. Use `auto/` prefix in any AI tool — **no combo creation needed**+3. OmniRoute dynamically builds a virtual combo from your active connections+4. Routes using LKGP (Last Known Good Provider) + 6-factor scoring+5. Session stickiness ensures consistent provider selection++**Dashboard indicator:** A blue banner at the top shows "Auto-Routing Active" with a link to `/dashboard/combos` for configuration.++**Monthly cost:** $0 (uses your existing free providers) or whatever your connected providers cost----## 🏗️ Architecture (10-second tour)+### Case 1: "I have a Claude Pro subscription"++**Problem:** Quota expires unused, rate limits during heavy coding sessions.```-Client → /v1/chat/completions → [CORS → Zod → Auth → Authz → Guardrails]- → handleChatCore() → [Cache → Rate limit → Combo routing]- → translateRequest → getExecutor → fetch upstream (with retry)- → response translation → SSE stream or JSON- → [Compliance audit] → response+Combo: "maximize-claude"+ 1. cc/claude-opus-4-7 (use subscription fully)+ 2. glm/glm-5.1 (cheap backup when quota out — $0.5/1M)+ 3. kr/claude-sonnet-4.5 (free emergency fallback via Kiro)++Compression: standard (caveman) — saves 30% tokens = stretch quota further+Monthly cost: $20 (subscription) + ~$3 (backup) = $23 total+vs. $20 + hitting limits + lost productivity = frustration```-**Major pieces:**+### Case 2: "I want $0 forever"++**Problem:** Can't afford subscriptions, need reliable AI for coding.++```+Combo: "free-forever"+ 1. kr/claude-sonnet-4.5 (Claude 4.5 free unlimited via Kiro)+ 2. if/kimi-k2-thinking (reasoning model free via Qoder)+ 3. pol/gpt-5 (GPT-5 free via Pollinations — no key)+ 4. lc/longcat-flash-lite (50M tokens/day free backup)++Compression: aggressive — saves 50% tokens = double your free quota+Monthly cost: $0+Quality: Production-ready models + 50% token savings+```-- **`src/app/`** — Next.js 16 App Router (60+ API routes + 30 dashboard pages)-- **`src/lib/`** — 50+ domain modules (db, a2a, memory, skills, guardrails, evals, …)-- **`open-sse/`** — Streaming engine workspace (31 executors, 9+8+9 translators, 80+ services, 37-tool MCP server)-- **`src/domain/`** — Pure business logic (policies, fallback, cost rules)-- **`src/server/`** — Server-only (authz pipeline, cors)+### Case 3: "I need 24/7 coding, no interruptions"-→ Deep dive: [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md) · [`docs/architecture/CODEBASE_DOCUMENTATION.md`](docs/architecture/CODEBASE_DOCUMENTATION.md)+**Problem:** Deadlines, can't afford any downtime.++```+Combo: "always-on"+ 1. cc/claude-opus-4-7 (best quality — subscription)+ 2. cx/gpt-5.5 (second subscription — OpenAI)+ 3. glm/glm-5.1 (cheap, resets daily — $0.5/1M)+ 4. minimax/MiniMax-M2.5 (cheapest paid — $0.3/1M)+ 5. kr/claude-sonnet-4.5 (free unlimited — never fails)++Compression: lite — saves 15% tokens passively, zero risk+Result: 5 layers of fallback = zero downtime+Monthly cost: $20-200 (subscriptions) + $5-10 (backup)+```++### Case 4: "I'm in a blocked region (Russia, China, Iran...)"++**Problem:** AI providers block my country, VPNs are slow.++```+Combo: "unblocked-ai"+ 1. kr/claude-sonnet-4.5 (free via Kiro + proxy)+ 2. pol/deepseek-r1 (Pollinations — no geo-block)+ 3. groq/llama-3.3-70b (Groq + proxy)++Proxy: Global proxy set in Settings → or per-provider proxy override+Result: Access ALL providers from ANY country+Monthly cost: $0 (free providers) + $0 (1proxy free marketplace)+```++### Case 5: "I want maximum token savings"++**Problem:** Token costs are eating my budget, need to squeeze every token.++```+Combo: "ultra-saver"+ 1. cc/claude-opus-4-7 (subscription — best quality)+ 2. glm/glm-5.1 (cheap backup)++Compression: ultra — saves 75% tokens+Result: 10K token prompt → 2.5K tokens sent+Montly savings: ~$150-300/month in token costs for heavy users+```++## 🧪 Evaluations (Evals)++OmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.++### Built-in Golden Set++The pre-loaded "OmniRoute Golden Set" contains test cases for:++- Greetings, math, geography, code generation+- JSON format compliance, translation, markdown generation+- Safety refusal (harmful content), counting, boolean logic++### Evaluation Strategies++| Strategy | Description | Example |+| ---------- | ------------------------------------------------ | -------------------------------- |+| `exact` | Output must match exactly | `"4"` |+| `contains` | Output must contain substring (case-insensitive) | `"Paris"` |+| `regex` | Output must match regex pattern | `"1.*2.*3"` |+| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |----## 🌍 i18n+## 📖 Setup Guide++### Connect Your Coding Tool++Point any OpenAI-compatible tool to OmniRoute:++```txt+Base URL: http://localhost:20128/v1+API Key: [from Dashboard → Endpoints]+```++| Tool | Config Location |+| --------------- | ----------------------------------------------------------------------------------------- |+| **Claude Code** | `claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp/stream` |+| **Codex CLI** | `OPENAI_BASE_URL=http://localhost:20128/v1 OPENAI_API_KEY=your-key codex` |+| **Cursor** | Settings → Models → Add Model → Override Base URL |+| **Cline** | Extension settings → Custom API Base URL |+| **OpenClaw** | `OPENAI_BASE_URL=http://localhost:20128/v1 openclaw` |+| **Gemini CLI** | Uses native OAuth via OmniRoute — connect in Providers |-UI translated to **30 languages** with full RTL support for Arabic and Hebrew.+### Protocols (MCP + A2A)-🌐 [English](README.md) · [Português](docs/i18n/pt-BR/README.md) · [Español](docs/i18n/es/README.md) · [Français](docs/i18n/fr/README.md) · [Deutsch](docs/i18n/de/README.md) · [中文](docs/i18n/zh-CN/README.md) · [日本語](docs/i18n/ja/README.md) · [한국어](docs/i18n/ko/README.md) · [العربية](docs/i18n/ar/README.md) · [हिन्दी](docs/i18n/hi/README.md) · [Русский](docs/i18n/ru/README.md) · [+ 19 more](docs/i18n/)+```bash+# MCP (stdio transport)+omniroute --mcp++# A2A (JSON-RPC 2.0)+curl http://localhost:20128/.well-known/agent.json+```-→ Adding a language: [`docs/guides/I18N.md`](docs/guides/I18N.md)+### Key Environment Variables++| Variable | Default | Purpose |+| -------------------- | -------------- | ----------------------------------------- |+| `PORT` | `20128` | API and dashboard port |+| `DASHBOARD_PORT` | — | Separate dashboard port (split-port mode) |+| `REQUIRE_API_KEY` | `false` | Require API key for all requests |+| `DATA_DIR` | `~/.omniroute` | Database and config storage |+| `REQUEST_TIMEOUT_MS` | `600000` | Upstream response timeout |++<details>+<summary><b>📖 Full Setup Guide — All CLI tools, protocols, and environment variables</b></summary>++📖 **Complete documentation:**++- [User Guide](docs/USER_GUIDE.md) — Providers, combos, CLI integration+- [API Reference](docs/API_REFERENCE.md) — All endpoints with examples+- [MCP Server](open-sse/mcp-server/README.md) — 37 tools, IDE configs+- [A2A Server](src/lib/a2a/README.md) — JSON-RPC, skills, streaming+- [Environment Config](docs/ENVIRONMENT.md) — Complete `.env` reference+- [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) — VM + nginx + Cloudflare++</details>----## 🤝 Community+## ❓ Frequently Asked Questions++<details>+<summary><b>📊 Why does my dashboard show high costs if I'm using free models?</b></summary>++The dashboard tracks your token usage and displays **estimated costs** as if you were using paid APIs directly. This is **not actual billing** — it's a reference to show how much you're saving.++**Example:**++- **Dashboard shows:** "$290 total cost"+- **Reality:** You're using Kiro + Qoder (FREE unlimited)+- **Your actual cost:** **$0.00**+- **What $290 means:** Amount you **saved** by using free models instead of paid APIs!++The cost display is a "savings tracker" to help you understand your usage patterns and optimization opportunities.++</details>++<details>+<summary><b>💳 Will I be charged by OmniRoute?</b></summary>++**No.** OmniRoute is free, open-source software that runs on your own computer. It never charges you anything.++**You only pay:**++- ✅ **Subscription providers** (Claude Code $20/mo, Codex $20-200/mo) → Pay them directly on their websites+- ✅ **API key providers** (DeepSeek, xAI, etc.) → Pay them directly, OmniRoute just routes your requests+- ❌ **OmniRoute itself** → **Never charges anything, ever**++OmniRoute is a local proxy/router. It doesn't have your credit card, can't send invoices, and has no billing system. It's completely free software.++</details>++<details>+<summary><b>🆓 Are FREE providers really unlimited?</b></summary>++**Yes!** The current FREE providers are genuinely free with **no hidden charges**:++- **Kiro AI**: Free unlimited Claude Sonnet/Haiku via AWS Builder ID / Google / GitHub OAuth+- **Qoder**: Free unlimited kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 via PAT token+- **Pollinations AI**: No API key needed — GPT-5, Claude, DeepSeek, Llama 4+- **LongCat Flash-Lite**: 50M tokens/day — largest free quota available+- **Cloudflare Workers AI**: 10K Neurons/day — 50+ models at the edge++OmniRoute just routes your requests to them — there's no "catch" or future billing.++</details>++<details>+<summary><b>💰 How do I minimize my actual AI costs?</b></summary>++**Free-First Strategy:**++1. **Start with 100% free combo:**++ ```+ 1. kr/claude-sonnet-4.5 (Kiro — unlimited free)+ 2. if/kimi-k2-thinking (Qoder — unlimited free)+ 3. pol/gpt-5 (Pollinations — no key needed)+ ```++ **Cost: $0/month**++2. **Enable Prompt Compression** — even `lite` mode saves ~15% passively++3. **Add cheap backup** only if you need it:++ ```+ 4. glm/glm-5.1 ($0.5/1M tokens)+ ```++ **Additional cost: Only pay for what you actually use**++4. **Use subscription providers last** — only if you already have them. OmniRoute helps maximize their value through quota tracking.++**Result:** Most users can operate at **$0/month** using only free tiers!++</details>++<details>+<summary><b>🗜️ Will compression affect response quality?</b></summary>++**No.** Compression only affects the **input** (your prompt), not the model's response. Each mode has been designed to preserve technical accuracy:++- **Lite** (~15%): Only whitespace/formatting — zero semantic change+- **Standard** (~30%): Removes filler words ("please", "I think", "basically") — same meaning+- **Aggressive** (~50%): Summarizes old messages + compresses tool outputs — core context preserved+- **Ultra** (~75%): Heuristic pruning — use only when token budget is critical-- 🌐 **Website:** [omniroute.online](https://omniroute.online)-- 📦 **npm:** [omniroute](https://www.npmjs.com/package/omniroute)-- 🐳 **Docker Hub:** [diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)-- 💬 **WhatsApp (BR):** Brazilian community group — see README link-- 🐛 **Issues:** [GitHub Issues](https://github.com/diegosouzapw/OmniRoute/issues)-- 💡 **Discussions:** [GitHub Discussions](https://github.com/diegosouzapw/OmniRoute/discussions)+Code blocks, URLs, JSON, and structured data are **always protected** from compression via the preservation engine.++</details>++<details>+<summary><b>🌍 Does OmniRoute work in countries where AI is blocked?</b></summary>++**Yes!** OmniRoute has a 3-level proxy system:++1. **Global proxy** — all requests go through your proxy+2. **Per-provider proxy** — different proxy per provider+3. **Per-API-key proxy** — different proxy per key++Plus the **1proxy free marketplace** for community-shared proxies. Users in Russia, China, Iran, and other restricted regions can access all 160+ providers through OmniRoute's proxy infrastructure.++See the [Proxy Guide](docs/PROXY_GUIDE.md) for setup instructions.++</details>----## ❤️ Contributing+## 🐛 Troubleshooting-We welcome PRs! Start with:+| Problem | Quick Fix |+| --------------------------------------------- | ------------------------------------------------------------------------------------ |+| **"Language model did not provide messages"** | Provider quota exhausted → check quota tracker, use combo fallback |+| **Rate limiting (429)** | Add fallback combo: `cc/claude → glm/glm-4.7 → if/kimi-k2-thinking` |+| **OAuth token expired** | Auto-refreshed by OmniRoute. If stuck: delete + re-auth in Providers |+| **`unsupported_country_region_territory`** | Configure proxy in Settings → Proxy (see [Proxy Guide](docs/PROXY_GUIDE.md)) |+| **Docker SQLite locks** | Use `--stop-timeout 40` for clean WAL checkpoint on shutdown |+| **Node.js runtime errors** | Use Node.js `>=20.20.2 <21`, `>=22.22.2 <23`, or `>=24.0.0 <25` (24 LTS recommended) |+| **`system-info` for bug reports** | Run `npm run system-info` and attach `system-info.txt` to your issue |-1. Read [`CONTRIBUTING.md`](CONTRIBUTING.md) — setup, conventional commits, testing-2. Pick an issue labeled [`good first issue`](https://github.com/diegosouzapw/OmniRoute/labels/good%20first%20issue)-3. Branch from `main` (`feat/*`, `fix/*`, `docs/*`, `refactor/*`, `test/*`, `chore/*`)-4. Hooks will run lint + test on commit/push+📖 **Full troubleshooting guide:** [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md)-**Adding a provider?** [`docs/architecture/ARCHITECTURE.md § Adding a New Provider`](docs/architecture/ARCHITECTURE.md)-**Adding an MCP tool?** [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md)-**Adding an A2A skill?** [`docs/frameworks/A2A-SERVER.md § Adding a New Skill`](docs/frameworks/A2A-SERVER.md)+## 🛠️ Tech Stack++<details>+<summary><b>Click to expand tech stack details</b></summary>++- **Runtime**: Node.js 20.20.2+, 22.22.2+, or 24.x LTS (24 LTS recommended)+- **Language**: TypeScript 5.9 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)+- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4+- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills+- **Schemas**: Zod (MCP tool I/O validation, API contracts)+- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)+- **Streaming**: Server-Sent Events (SSE) + WebSocket bridge (`/v1/ws`)+- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization+- **Testing**: Node.js test runner + Vitest (**4,690+ test cases** across 517 files — unit, integration, E2E, security, ecosystem)+- **Platforms**: Desktop (Electron), Android (Termux), PWA (any browser)+- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)+- **Website**: [omniroute.online](https://omniroute.online)+- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)+- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)+- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing++</details>----## 🔒 Security+## 📖 Documentation++### 📘 Getting Started++| Document | Description |+| ------------------------------------- | ----------------------------------------------------------------------------- |+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |+| [Setup Guide](docs/SETUP_GUIDE.md) | Full install methods, CLI tool configs, protocol setup, timeout tuning |+| [CLI Tools Guide](docs/CLI-TOOLS.md) | Per-tool setup for Claude Code, Codex, Cursor, Cline, OpenClaw, Kilo, Copilot |+| [Quick Start](README.md#-quick-start) | 3-step install → connect → configure |++### 🔧 Operations & Deployment++| Document | Description |+| ---------------------------------------------------- | -------------------------------------------------------------- |+| [Docker Guide](docs/DOCKER_GUIDE.md) | Docker run, Compose profiles, Caddy HTTPS, tunnels, image tags |+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |+| [Fly.io Deployment](docs/FLY_IO_DEPLOYMENT_GUIDE.md) | Deploy to Fly.io with persistent storage |+| [Termux Guide](docs/TERMUX_GUIDE.md) | Run OmniRoute on Android via Termux |+| [PWA Guide](docs/PWA_GUIDE.md) | Progressive Web App install, caching, architecture |+| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |+| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |++### 🧠 Features & Architecture++| Document | Description |+| ---------------------------------------------------------------- | ----------------------------------------------------------------------------- |+| [Architecture](docs/ARCHITECTURE.md) | System architecture, data flow, and internals |+| [Compression Guide](docs/COMPRESSION_GUIDE.md) | 7-option pipeline: off / lite / standard / aggressive / ultra / RTK / stacked |+| [RTK Compression](docs/RTK_COMPRESSION.md) | Command-output compression, filters, trust, verify, raw-output recovery |+| [Compression Engines](docs/COMPRESSION_ENGINES.md) | Caveman, RTK, stacked pipelines, dashboard/API/MCP surfaces |+| [Compression Rules Format](docs/COMPRESSION_RULES_FORMAT.md) | JSON rule-pack schemas for Caveman and RTK filters |+| [Compression Language Packs](docs/COMPRESSION_LANGUAGE_PACKS.md) | Language detection and Caveman rule-pack authoring |+| [Resilience Guide](docs/RESILIENCE_GUIDE.md) | Circuit breakers, cooldowns, queue, anti-thundering herd, TLS spoofing |+| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |+| [Proxy Guide](docs/PROXY_GUIDE.md) | 3-level proxy system, 1proxy marketplace, registry CRUD |+| [Free Tiers](docs/FREE_TIERS.md) | 25+ free API providers consolidated directory |+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |+| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |++### 🤖 Protocols & APIs++| Document | Description |+| ------------------------------------------- | --------------------------------------------------- |+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |+| [MCP Server](open-sse/mcp-server/README.md) | 29 MCP tools, IDE configs, Python/TS/Go clients |+| [MCP Server Guide](docs/MCP-SERVER.md) | MCP installation, transports, and tool reference |+| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |+| [A2A Server Guide](docs/A2A-SERVER.md) | A2A agent card, tasks, skills, and streaming |++### 📋 Project & Quality++| Document | Description |+| ---------------------------------------------- | ----------------------------------------------- |+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |+| [i18n Guide](docs/I18N.md) | 40+ language support, translation workflow, RTL |+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |+| [Coverage Plan](docs/COVERAGE_PLAN.md) | Test coverage strategy and 4,690+ test suite |-- **Reporting:** see [`SECURITY.md`](SECURITY.md) for disclosure policy-- **Supported versions:** 3.8.x (Active), 3.7.x (Security only)-- **Secrets:** never commit. Use `.env` (auto-generated from `.env.example` on first install) or vaults-- **Encryption:** credentials at rest with AES-256-GCM-- **Authz:** route-aware classification (`src/server/authz/`) — see [`docs/architecture/AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md)-- **Guardrails:** PII masking, prompt injection detection — hot-reloadable+---++## ⭐ Top Contributors++> OmniRoute is shaped by a passionate open-source community. These individuals have made exceptional contributions that directly impact the quality, stability, and reach of the project. **Thank you.**++<table>+ <tr>+ <td align="center" width="160">+ <a href="https://github.com/oyi77">+ <img src="https://github.com/oyi77.png" width="80" style="border-radius:50%" alt="oyi77"/><br/>+ <b>oyi77</b>+ </a><br/>+ <sub>🥇 190 commits • +72K lines</sub><br/>+ <sub>Analytics engine, SQL aggregations,<br/>proxy marketplace, test coverage</sub>+ </td>+ <td align="center" width="160">+ <a href="https://github.com/christopher-s">+ <img src="https://github.com/christopher-s.png" width="80" style="border-radius:50%" alt="Chris Staley"/><br/>+ <b>Chris Staley</b>+ </a><br/>+ <sub>🥈 72 commits • +5.7K lines</sub><br/>+ <sub>SSE stream hardening, Responses API,<br/>Gemini pagination, test regression fixes</sub>+ </td>+ <td align="center" width="160">+ <a href="https://github.com/zenobit">+ <img src="https://github.com/zenobit.png" width="80" style="border-radius:50%" alt="zenobit"/><br/>+ <b>zenobit</b>+ </a><br/>+ <sub>🥉 62 commits • +24K lines</sub><br/>+ <sub>CI/CD pipeline, i18n for 33 languages,<br/>Void Linux package, platform fixes</sub>+ </td>+ <td align="center" width="160">+ <a href="https://github.com/rdself">+ <img src="https://github.com/rdself.png" width="80" style="border-radius:50%" alt="R.D. & Randi"/><br/>+ <b>R.D. & Randi</b>+ </a><br/>+ <sub>🏅 107 commits • +28K lines</sub><br/>+ <sub>Endpoints page, tunnel integrations,<br/>Docker workflows, A2A status, compression UI</sub>+ </td>+ <td align="center" width="160">+ <a href="https://github.com/benzntech">+ <img src="https://github.com/benzntech.png" width="80" style="border-radius:50%" alt="benzntech"/><br/>+ <b>benzntech</b>+ </a><br/>+ <sub>🏅 20 commits • +7.5K lines</sub><br/>+ <sub>Electron desktop app, auto-updater,<br/>release build workflows, cross-platform CI</sub>+ </td>+ </tr>+</table>++> 🙏 These contributors' features, bug fixes, and infrastructure improvements are a **core part** of what makes OmniRoute reliable and feature-rich. Every pull request, every test case, and every i18n translation file matters. Open source is built by people like them.----## 📄 License+## 👥 Contributors++[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)++### How to Contribute-[MIT](LICENSE) © 2025-2026 [Diego Souza](https://github.com/diegosouzapw)+1. Fork the repository+2. Create your feature branch (`git checkout -b feature/amazing-feature`)+3. Commit your changes (`git commit -m 'Add amazing feature'`)+4. Push to the branch (`git push origin feature/amazing-feature`)+5. Open a Pull Request-Free forever. Self-hosted. No tracking. No cloud lock-in.+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.++### Releasing a New Version++```bash+# Create a release — npm publish happens automatically+gh release create v2.0.0 --title "v2.0.0" --generate-notes+```----<div align="center">+## 📊 Star History++<a href="https://www.star-history.com/?repos=diegosouzapw%2Fomniroute&type=date&legend=top-left">+ <picture>+ <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&theme=dark&legend=top-left" />+ <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left" />+ <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left" />+ </picture>+</a>++## 🌍 StarMapper++<a href="https://starmapper.bruniaux.com/diegosouzapw/omniroute">+ <picture>+ <source media="(prefers-color-scheme: dark)" srcset="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=dark" />+ <source media="(prefers-color-scheme: light)" srcset="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=light" />+ <img alt="StarMapper" src="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute" />+ </picture>+</a>++## 🙏 Acknowledgments++Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.-**[⬆ Back to top](#-omniroute)** · Built with ❤️ for the open-source AI community.+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** by **[router-for-me](https://github.com/router-for-me)** — the original Go implementation that inspired this JavaScript port.-<sub>OmniRoute v3.8.0 · Node ≥20.20.2 · MIT License</sub>+Special thanks to **[Caveman](https://github.com/JuliusBrussee/caveman)** by **[JuliusBrussee](https://github.com/JuliusBrussee)** (⭐ 51K+) — the viral "why use many token when few token do trick" project whose caveman-speak compression philosophy inspired OmniRoute's standard compression mode and 30+ filler/condensation regex rules.+Special thanks to **[RTK - Rust Token Killer](https://github.com/rtk-ai/rtk)** by **[RTK AI](https://github.com/rtk-ai)** — the high-performance command-output compression project whose terminal, build, test, git, and tool-output filtering model inspired OmniRoute's RTK engine, JSON filter DSL, raw-output recovery, and stacked RTK → Caveman compression pipeline.++---++## 📄 License++MIT License - see [LICENSE](LICENSE) for details.++---++<div align="center">+ <sub>Built with ❤️ for developers who code 24/7</sub>+ <br/>+ <sub><a href="https://omniroute.online">omniroute.online</a></sub></div>+<!-- GitHub Discussions enabled for community Q&A -->diff --git a/bin/cli/commands/config.mjs b/bin/cli/commands/config.mjsnew file mode 100644index 0000000000..32d61cba3f--- /dev/null+++ b/bin/cli/commands/config.mjs@@ -0,0 +1,182 @@+import { parseArgs, getStringFlag, hasFlag } from "../args.mjs";+import { printHeading, printInfo, printSuccess, printError } from "../io.mjs";+import { resolveDataDir } from "../data-dir.mjs";+import path from "node:path";+import fs from "node:fs";++function printConfigHelp() {+ console.log(`+Usage:+ omniroute config list List all CLI tools and config status+ omniroute config get <tool> Show current config for a tool+ omniroute config set <tool> [options] Write config for a tool+ omniroute config validate <tool> Validate config format without writing++Options:+ --base-url <url> OmniRoute API base URL (default: http://localhost:20128/v1)+ --api-key <key> API key for the tool+ --model <model> Model identifier (where applicable)+ --json Output as JSON+ --non-interactive Do not prompt for confirmation+ --yes Skip confirmation prompt+ --help Show this help++Tools: claude, codex, opencode, cline, kilocode, continue+`);+}++function ensureBackup(configPath) {+ if (!fs.existsSync(configPath)) return;+ const backupDir = path.join(path.dirname(configPath), ".omniroute.bak");+ if (!fs.existsSync(backupDir)) fs.mkdirSync(backupDir, { recursive: true });+ const backupPath = path.join(backupDir, path.basename(configPath) + ".bak");+ fs.copyFileSync(configPath, backupPath);+ return backupPath;+}++export async function runConfigCommand(argv) {+ const { flags, positionals } = parseArgs(argv);++ if (hasFlag(flags, "help") || hasFlag(flags, "h") || positionals.length === 0) {+ printConfigHelp();+ return 0;+ }++ const subcommand = positionals[0];+ const toolId = positionals[1];++ if (subcommand === "list") {+ const { detectAllTools } = await import("../../../src/lib/cli-helper/tool-detector.js");+ const tools = await detectAllTools();++ if (hasFlag(flags, "json")) {+ console.log(JSON.stringify(tools, null, 2));+ } else {+ printHeading("CLI Tool Configuration Status");+ for (const t of tools) {+ const status = t.configured+ ? "✓ Configured"+ : t.installed+ ? "✗ Not configured"+ : "✗ Not installed";+ console.log(` ${t.name.padEnd(14)} ${status}`);+ if (t.version) console.log(` version: ${t.version}`);+ console.log(` config: ${t.configPath}`);+ }+ }+ return 0;+ }++ if (subcommand === "get") {+ if (!toolId) {+ printError("Tool ID required. Usage: omniroute config get <tool>");+ return 1;+ }+ const { detectTool } = await import("../../../src/lib/cli-helper/tool-detector.js");+ const tool = await detectTool(toolId);+ if (!tool) {+ printError(`Unknown tool: ${toolId}`);+ return 1;+ }+ if (hasFlag(flags, "json")) {+ console.log(JSON.stringify(tool, null, 2));+ } else {+ printHeading(`${tool.name} Configuration`);+ console.log(` Installed: ${tool.installed ? "Yes" : "No"}`);+ console.log(` Configured: ${tool.configured ? "Yes" : "No"}`);+ console.log(` Config: ${tool.configPath}`);+ if (tool.version) console.log(` Version: ${tool.version}`);+ if (tool.configContents) {+ console.log(`\n Contents:`);+ console.log(tool.configContents);+ }+ }+ return 0;+ }++ if (subcommand === "set") {+ if (!toolId) {+ printError("Tool ID required. Usage: omniroute config set <tool> [options]");+ return 1;+ }++ const baseUrl =+ getStringFlag(flags, "base-url", "OMNIROUTE_BASE_URL") || "http://localhost:20128/v1";+ const apiKey = getStringFlag(flags, "api-key", "OMNIROUTE_API_KEY");+ const model = getStringFlag(flags, "model");++ if (!apiKey) {+ printError("API key required. Use --api-key or set OMNIROUTE_API_KEY.");+ return 1;+ }++ const { generateConfig } =+ await import("../../../src/lib/cli-helper/config-generator/index.js");+ const result = await generateConfig(toolId, { baseUrl, apiKey, model });++ if (!result.success) {+ printError(result.error || "Failed to generate config");+ return 1;+ }++ const nonInteractive = hasFlag(flags, "non-interactive") || hasFlag(flags, "yes");++ if (!nonInteractive) {+ console.log(`\n About to write config to: ${result.configPath}`);+ console.log(` Content preview:\n`);+ console.log(result.content);+ console.log("");++ const readline = await import("node:readline");+ const rl = readline.createInterface({ input: process.stdin, output: process.stdout });+ const answer = await new Promise((resolve) => rl.question("Proceed? [y/N] ", resolve));+ rl.close();++ if (!/^y(es)?$/i.test(answer)) {+ console.log("Aborted.");+ return 0;+ }+ }++ const dir = path.dirname(result.configPath);+ if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });++ const backupPath = ensureBackup(result.configPath);+ if (backupPath) printInfo(`Backup saved to: ${backupPath}`);++ fs.writeFileSync(result.configPath, result.content, "utf-8");+ printSuccess(`Config written to ${result.configPath}`);+ return 0;+ }++ if (subcommand === "validate") {+ if (!toolId) {+ printError("Tool ID required. Usage: omniroute config validate <tool>");+ return 1;+ }++ const baseUrl =+ getStringFlag(flags, "base-url", "OMNIROUTE_BASE_URL") || "http://localhost:20128/v1";+ const apiKey = getStringFlag(flags, "api-key", "OMNIROUTE_API_KEY") || "test-key";+ const model = getStringFlag(flags, "model");++ const { generateConfig } =+ await import("../../../src/lib/cli-helper/config-generator/index.js");+ const result = await generateConfig(toolId, { baseUrl, apiKey, model });++ if (!result.success) {+ printError(`Validation failed: ${result.error}`);+ return 1;+ }++ printSuccess(`Config for ${toolId} is valid`);+ if (hasFlag(flags, "json")) {+ console.log(JSON.stringify({ valid: true, content: result.content }, null, 2));+ }+ return 0;+ }++ printError(`Unknown subcommand: ${subcommand}`);+ printConfigHelp();+ return 1;+}diff --git a/bin/cli/commands/doctor.mjs b/bin/cli/commands/doctor.mjsindex 2f4543b6b9..3fe11b1a31 100644--- a/bin/cli/commands/doctor.mjs+++ b/bin/cli/commands/doctor.mjs@@ -466,6 +466,15 @@ export async function collectDoctorChecks(context = {}, options = {}) {checks.push(await checkServerLiveness(options));}+ // CLI tool health checks+ try {+ const { collectCliToolChecks } = await import("../../../src/lib/cli-helper/doctor/checks.js");+ const cliChecks = await collectCliToolChecks();+ checks.push(...cliChecks);+ } catch (err) {+ checks.push(warn("CLI Tools", `Could not run CLI tool checks: ${err.message}`));+ }+return {dataDir,dbPath,@@ -493,7 +502,7 @@ Options:--liveness-url <url> Full health endpoint URL overrideChecks:- config, database, storage/encryption, ports, Node runtime, native binary, memory, server liveness+ config, database, storage/encryption, ports, Node runtime, native binary, memory, server liveness, CLI tools`);}diff --git a/bin/cli/commands/logs.mjs b/bin/cli/commands/logs.mjsnew file mode 100644index 0000000000..28763922b1--- /dev/null+++ b/bin/cli/commands/logs.mjs@@ -0,0 +1,83 @@+import { parseArgs, getStringFlag, hasFlag } from "../args.mjs";+import { printHeading, printInfo, printError } from "../io.mjs";++function printLogsHelp() {+ console.log(`+Usage:+ omniroute logs [options]++Options:+ --follow Stream logs in real-time+ --filter <level> Filter by level (error, warn, info) — comma-separated+ --lines <n> Number of lines to fetch (default: 100)+ --timeout <ms> Connection timeout in ms (default: 30000)+ --base-url <url> OmniRoute API base URL (default: http://localhost:20128)+ --json Output as JSON+ --help Show this help+`);+}++export async function runLogsCommand(argv) {+ const { flags } = parseArgs(argv);++ if (hasFlag(flags, "help") || hasFlag(flags, "h")) {+ printLogsHelp();+ return 0;+ }++ const baseUrl = getStringFlag(flags, "base-url") || "http://localhost:20128";+ const follow = hasFlag(flags, "follow");+ const filter = getStringFlag(flags, "filter");+ const lines = getStringFlag(flags, "lines") || "100";+ const timeout = parseInt(getStringFlag(flags, "timeout") || "30000", 10);++ const filters = filter ? filter.split(",").map((f) => f.trim()) : [];++ const { createLogStream } = await import("../../../src/lib/cli-helper/log-streamer.js");+ const { stream, stop } = createLogStream({ baseUrl, filters, follow, timeout });++ const reader = stream.getReader();+ const decoder = new TextDecoder();+ let buffer = "";++ const processLine = (line) => {+ if (!line.trim()) return;+ if (hasFlag(flags, "json")) {+ console.log(line);+ return;+ }+ try {+ const parsed = JSON.parse(line);+ const level = parsed.level || "info";+ const ts = parsed.timestamp || new Date().toISOString();+ const msg = parsed.message || JSON.stringify(parsed);+ const prefix =+ { error: "\x1b[31m[ERR]", warn: "\x1b[33m[WRN]", info: "\x1b[36m[INF]" }[level] || "[INF]";+ console.log(`${prefix}\x1b[0m ${ts} ${msg}`);+ } catch {+ console.log(line);+ }+ };++ try {+ while (true) {+ const { done, value } = await reader.read();+ if (done) break;+ buffer += decoder.decode(value, { stream: true });+ const lines = buffer.split("\n");+ buffer = lines.pop() || "";+ for (const line of lines) processLine(line);+ }+ if (buffer) processLine(buffer);+ } catch (err) {+ if (err.name === "AbortError") {+ printInfo("Log stream stopped.");+ } else {+ printError(`Log stream error: ${err.message}`);+ }+ } finally {+ stop();+ }++ return 0;+}diff --git a/bin/cli/commands/provider-cmd.mjs b/bin/cli/commands/provider-cmd.mjsnew file mode 100644index 0000000000..bbd977d8a3--- /dev/null+++ b/bin/cli/commands/provider-cmd.mjs@@ -0,0 +1,278 @@+import { parseArgs, getStringFlag, hasFlag } from "../args.mjs";+import { printHeading, printInfo, printSuccess, printError } from "../io.mjs";+import { resolveDataDir, resolveStoragePath } from "../data-dir.mjs";+import path from "node:path";+import fs from "node:fs";++function printProviderHelp() {+ console.log(`+Usage:+ omniroute provider add <name> [options] Add a provider connection+ omniroute provider list List configured providers+ omniroute provider remove <name|id> Remove a provider connection+ omniroute provider test <name|id> Test a provider connection+ omniroute provider default <name|id> Set default provider++Options:+ --provider <id> Provider id (e.g., openai, anthropic, omniroute)+ --api-key <key> API key for the provider+ --provider-name <name> Display name for the connection+ --default-model <model> Default model to use+ --base-url <url> Custom base URL override+ --json Output as JSON+ --yes Skip confirmation+ --help Show this help+`);+}++export async function runProviderCommand(argv) {+ const { flags, positionals } = parseArgs(argv);++ if (hasFlag(flags, "help") || hasFlag(flags, "h") || positionals.length === 0) {+ printProviderHelp();+ return 0;+ }++ const subcommand = positionals[0];++ if (subcommand === "add") {+ const providerName = positionals[1] || getStringFlag(flags, "provider");+ const apiKey = getStringFlag(flags, "api-key");+ const displayName = getStringFlag(flags, "provider-name");+ const defaultModel = getStringFlag(flags, "default-model");+ const baseUrl = getStringFlag(flags, "base-url");++ if (!providerName) {+ printError("Provider name required. Usage: omniroute provider add <name>");+ return 1;+ }++ if (providerName === "omniroute") {+ // Special case: add OmniRoute as a provider in OpenCode config+ const opencodePath = path.join(+ process.env.HOME || os.homedir(),+ ".config",+ "opencode",+ "opencode.json"+ );+ const { generateConfig } =+ await import("../../../src/lib/cli-helper/config-generator/index.js");+ const result = await generateConfig("opencode", {+ baseUrl: baseUrl || "http://localhost:20128/v1",+ apiKey: apiKey || "",+ });++ if (!result.success) {+ printError(result.error || "Failed to generate config");+ return 1;+ }++ if (!hasFlag(flags, "yes")) {+ console.log(`\n About to write OpenCode config to: ${opencodePath}`);+ console.log(` Content:\n`);+ console.log(result.content);+ console.log("");+ const readline = await import("node:readline");+ const rl = readline.createInterface({ input: process.stdin, output: process.stdout });+ const answer = await new Promise((resolve) => rl.question("Proceed? [y/N] ", resolve));+ rl.close();+ if (!/^y(es)?$/i.test(answer)) {+ printInfo("Aborted.");+ return 0;+ }+ }++ const dir = path.dirname(opencodePath);+ if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });+ fs.writeFileSync(opencodePath, result.content, "utf-8");+ printSuccess(`OpenCode config written to ${opencodePath}`);+ return 0;+ }++ // Generic provider addition via SQLite+ const dbPath = resolveStoragePath(resolveDataDir());+ if (!fs.existsSync(dbPath)) {+ printError("Database not found. Run `omniroute setup` first.");+ return 1;+ }++ const { default: Database } = await import("better-sqlite3");+ const db = new Database(dbPath);++ try {+ const stmt = db.prepare(`+ INSERT INTO provider_connections (provider, name, api_key, default_model, provider_specific_data)+ VALUES (?, ?, ?, ?, ?)+ `);+ const specificData = baseUrl ? JSON.stringify({ baseUrl }) : null;+ stmt.run(+ providerName,+ displayName || providerName,+ apiKey || "",+ defaultModel || null,+ specificData+ );+ printSuccess(`Provider "${displayName || providerName}" added`);+ } finally {+ db.close();+ }++ return 0;+ }++ if (subcommand === "list") {+ const dbPath = resolveStoragePath(resolveDataDir());+ if (!fs.existsSync(dbPath)) {+ if (isJson()) console.log(JSON.stringify([]));+ else printInfo("No database found. Run `omniroute setup` first.");+ return 0;+ }++ const { default: Database } = await import("better-sqlite3");+ const db = new Database(dbPath);+ try {+ const rows = db+ .prepare("SELECT id, provider, name, default_model FROM provider_connections")+ .all();+ if (isJson()) {+ console.log(JSON.stringify(rows, null, 2));+ } else {+ printHeading("Configured Providers");+ for (const r of rows) {+ console.log(+ ` [${r.id}] ${r.name} (${r.provider})${r.default_model ? ` — model: ${r.default_model}` : ""}`+ );+ }+ }+ } finally {+ db.close();+ }+ return 0;+ }++ if (subcommand === "remove") {+ const target = positionals[1];+ if (!target) {+ printError("Provider name or ID required. Usage: omniroute provider remove <name|id>");+ return 1;+ }++ const dbPath = resolveStoragePath(resolveDataDir());+ if (!fs.existsSync(dbPath)) {+ printError("Database not found.");+ return 1;+ }++ const { default: Database } = await import("better-sqlite3");+ const db = new Database(dbPath);+ try {+ const isId = /^\d+$/.test(target);+ const stmt = isId+ ? db.prepare("DELETE FROM provider_connections WHERE id = ?")+ : db.prepare("DELETE FROM provider_connections WHERE name = ? OR provider = ?");+ const result = stmt.run(isId ? parseInt(target, 10) : target);+ if (result.changes > 0) {+ printSuccess(`Removed ${result.changes} provider(s)`);+ } else {+ printError("Provider not found");+ }+ } finally {+ db.close();+ }+ return 0;+ }++ if (subcommand === "test") {+ const target = positionals[1];+ if (!target) {+ printError("Provider name or ID required. Usage: omniroute provider test <name|id>");+ return 1;+ }++ const dbPath = resolveStoragePath(resolveDataDir());+ if (!fs.existsSync(dbPath)) {+ printError("Database not found.");+ return 1;+ }++ const { default: Database } = await import("better-sqlite3");+ const db = new Database(dbPath);+ try {+ const isId = /^\d+$/.test(target);+ const row = isId+ ? db.prepare("SELECT * FROM provider_connections WHERE id = ?").get(parseInt(target, 10))+ : db+ .prepare("SELECT * FROM provider_connections WHERE name = ? OR provider = ?")+ .get(target);++ if (!row) {+ printError("Provider not found");+ return 1;+ }++ const { testProviderApiKey } = await import("../provider-test.mjs");+ const result = await testProviderApiKey({+ provider: row.provider,+ apiKey: row.api_key,+ defaultModel: row.default_model,+ baseUrl: row.provider_specific_data ? JSON.parse(row.provider_specific_data).baseUrl : null,+ });++ if (isJson()) {+ console.log(JSON.stringify(result, null, 2));+ } else if (result.valid) {+ printSuccess(`Provider "${row.name}" is reachable`);+ } else {+ printError(`Provider test failed: ${result.error || "unknown error"}`);+ }+ } finally {+ db.close();+ }+ return 0;+ }++ if (subcommand === "default") {+ const target = positionals[1];+ if (!target) {+ printError("Provider name or ID required. Usage: omniroute provider default <name|id>");+ return 1;+ }++ const dbPath = resolveStoragePath(resolveDataDir());+ if (!fs.existsSync(dbPath)) {+ printError("Database not found.");+ return 1;+ }++ const { default: Database } = await import("better-sqlite3");+ const db = new Database(dbPath);+ try {+ const isId = /^\d+$/.test(target);+ const row = isId+ ? db.prepare("SELECT * FROM provider_connections WHERE id = ?").get(parseInt(target, 10))+ : db+ .prepare("SELECT * FROM provider_connections WHERE name = ? OR provider = ?")+ .get(target);++ if (!row) {+ printError("Provider not found");+ return 1;+ }++ db.prepare("UPDATE provider_connections SET is_default = 0").run();+ db.prepare("UPDATE provider_connections SET is_default = 1 WHERE id = ?").run(row.id);+ printSuccess(`Default provider set to "${row.name}"`);+ } finally {+ db.close();+ }+ return 0;+ }++ printError(`Unknown subcommand: ${subcommand}`);+ printProviderHelp();+ return 1;+}++function isJson() {+ return process.argv.includes("--json");+}diff --git a/bin/cli/commands/status.mjs b/bin/cli/commands/status.mjsnew file mode 100644index 0000000000..b7d3446aea--- /dev/null+++ b/bin/cli/commands/status.mjs@@ -0,0 +1,84 @@+import { parseArgs, getStringFlag, hasFlag } from "../args.mjs";+import { printHeading, printInfo, printSuccess } from "../io.mjs";+import { resolveDataDir, resolveStoragePath } from "../data-dir.mjs";+import path from "node:path";+import fs from "node:fs";+import os from "node:os";++function getPackageVersion() {+ try {+ const pkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), "package.json"), "utf-8"));+ return pkg.version || "unknown";+ } catch {+ return "unknown";+ }+}++function formatBytes(bytes) {+ if (bytes < 1024) return `${bytes} B`;+ if (bytes < 1048576) return `${(bytes / 1024).toFixed(1)} KB`;+ return `${(bytes / 1048576).toFixed(1)} MB`;+}++export async function runStatusCommand(argv) {+ const { flags } = parseArgs(argv);+ const isJson = hasFlag(flags, "json");+ const isVerbose = hasFlag(flags, "verbose");++ const dataDir = resolveDataDir();+ const dbPath = resolveStoragePath(dataDir);+ const version = getPackageVersion();++ const status = {+ version,+ dataDir,+ database: {+ exists: fs.existsSync(dbPath),+ path: dbPath,+ size: fs.existsSync(dbPath) ? formatBytes(fs.statSync(dbPath).size) : null,+ },+ configDir: path.join(dataDir, "config"),+ configExists: fs.existsSync(path.join(dataDir, "config")),+ };++ if (isVerbose || !isJson) {+ try {+ const { detectAllTools } = await import("../../../src/lib/cli-helper/tool-detector.js");+ const tools = await detectAllTools();+ status.tools = tools.map((t) => ({+ id: t.id,+ name: t.name,+ installed: t.installed,+ configured: t.configured,+ version: t.version || null,+ }));+ } catch {+ status.tools = "unavailable";+ }+ }++ if (isJson) {+ console.log(JSON.stringify(status, null, 2));+ return 0;+ }++ printHeading("OmniRoute Status");+ console.log(` Version: ${status.version}`);+ console.log(` Data Dir: ${status.dataDir}`);+ console.log(+ ` Database: ${status.database.exists ? "Found" : "Not found"} (${status.database.size || "N/A"})`+ );+ console.log(` Config Dir: ${status.configExists ? "Exists" : "Not found"}`);++ if (status.tools) {+ console.log("\n CLI Tools:");+ for (const t of status.tools) {+ const icon = t.configured ? "✓" : t.installed ? "~" : "✗";+ console.log(+ ` ${icon} ${t.name.padEnd(14)} ${t.installed ? "installed" : "not installed"}${t.version ? ` (${t.version})` : ""}`+ );+ }+ }++ return 0;+}diff --git a/bin/cli/commands/update.mjs b/bin/cli/commands/update.mjsnew file mode 100644index 0000000000..8b8a394090--- /dev/null+++ b/bin/cli/commands/update.mjs@@ -0,0 +1,166 @@+import { parseArgs, getStringFlag, hasFlag } from "../args.mjs";+import { printHeading, printInfo, printSuccess, printError } from "../io.mjs";+import { homedir } from "node:os";+import path from "node:path";+import { execFile } from "node:child_process";+import { promisify } from "node:util";++const execFileAsync = promisify(execFile);++function printUpdateHelp() {+ console.log(`+Usage:+ omniroute update [options]++Options:+ --check Check for available update without applying+ --dry-run Show what would be updated without applying+ --backup Create backup before updating (default: true)+ --no-backup Skip backup creation+ --help Show this help++Environment:+ OMNIRoute_AUTO_UPDATE Set to "true" to enable auto-update check on startup+`);+}++async function getCurrentVersion() {+ try {+ const { readFileSync } = await import("node:fs");+ const pkg = JSON.parse(readFileSync(path.join(process.cwd(), "package.json"), "utf-8"));+ return pkg.version;+ } catch {+ return null;+ }+}++async function getLatestVersion() {+ try {+ const { stdout } = await execFileAsync("npm", ["view", "omniroute", "version"], {+ timeout: 15000,+ });+ return stdout.trim();+ } catch {+ return null;+ }+}++function compareVersions(a, b) {+ const pa = a.split(".").map(Number);+ const pb = b.split(".").map(Number);+ for (let i = 0; i < 3; i++) {+ if ((pa[i] || 0) > (pb[i] || 0)) return 1;+ if ((pa[i] || 0) < (pb[i] || 0)) return -1;+ }+ return 0;+}++async function createBackup() {+ const binPath = path.join(process.cwd(), "bin");+ const backupDir = path.join(homedir(), ".omniroute", "backups", `omniroute-${Date.now()}`);++ try {+ const { mkdirSync, copyFileSync, existsSync } = await import("node:fs");+ if (!existsSync(binPath)) return null;++ mkdirSync(backupDir, { recursive: true });+ const files = ["omniroute.mjs", "cli", "nodeRuntimeSupport.mjs", "mcp-server.mjs"];+ for (const f of files) {+ const src = path.join(binPath, f);+ if (existsSync(src)) {+ copyFileSync(src, path.join(backupDir, f));+ }+ }+ return backupDir;+ } catch {+ return null;+ }+}++export async function runUpdateCommand(argv) {+ const { flags } = parseArgs(argv);++ if (hasFlag(flags, "help") || hasFlag(flags, "h")) {+ printUpdateHelp();+ return 0;+ }++ const checkOnly = hasFlag(flags, "check");+ const dryRun = hasFlag(flags, "dry-run");+ const skipBackup = hasFlag(flags, "no-backup");++ const current = await getCurrentVersion();+ const latest = await getLatestVersion();++ if (!current) {+ printError("Could not determine current version");+ return 1;+ }++ if (!latest) {+ printError("Could not check latest version. Is npm available?");+ return 1;+ }++ printHeading("OmniRoute Update");+ console.log(` Current version: ${current}`);+ console.log(` Latest version: ${latest}`);++ const cmp = compareVersions(current, latest);+ if (cmp >= 0) {+ printSuccess("You are running the latest version!");+ return 0;+ }++ console.log(`\n Update available: ${current} → ${latest}`);++ if (checkOnly) {+ console.log("\n Run `omniroute update` to apply the update.");+ return 0;+ }++ if (dryRun) {+ console.log("\n [DRY RUN] Would run: npm install -g omniroute@latest");+ if (!skipBackup) console.log(" [DRY RUN] Would create backup in ~/.omniroute/backups/");+ return 0;+ }++ if (!skipBackup) {+ printInfo("Creating backup...");+ const backupPath = await createBackup();+ if (backupPath) {+ printSuccess(`Backup created: ${backupPath}`);+ } else {+ printError("Failed to create backup. Aborting update.");+ return 1;+ }+ }++ if (!hasFlag(flags, "yes")) {+ const readline = await import("node:readline");+ const rl = readline.createInterface({ input: process.stdin, output: process.stdout });+ const answer = await new Promise((resolve) =>+ rl.question(`Proceed with update to ${latest}? [y/N] `, resolve)+ );+ rl.close();+ if (!/^y(es)?$/i.test(answer)) {+ printInfo("Update aborted.");+ return 0;+ }+ }++ printInfo("Updating OmniRoute...");+ try {+ const { execSync } = await import("child_process");+ execSync("npm install -g omniroute@latest", { stdio: "inherit" });+ printSuccess(`Updated to version ${latest}`);+ printInfo("Run `omniroute --version` to verify.");+ return 0;+ } catch (err) {+ printError(`Update failed: ${err.message}`);+ printInfo("Restore from backup:");+ const backupDir = path.join(homedir(), ".omniroute", "backups");+ printInfo(` ls ${backupDir}`);+ return 1;+ }+}diff --git a/bin/cli/index.mjs b/bin/cli/index.mjsindex c9c8683016..a908b54745 100644--- a/bin/cli/index.mjs+++ b/bin/cli/index.mjs@@ -1,6 +1,11 @@import { runDoctorCommand } from "./commands/doctor.mjs";import { runProvidersCommand } from "./commands/providers.mjs";import { runSetupCommand } from "./commands/setup.mjs";+import { runConfigCommand } from "./commands/config.mjs";+import { runStatusCommand } from "./commands/status.mjs";+import { runLogsCommand } from "./commands/logs.mjs";+import { runUpdateCommand } from "./commands/update.mjs";+import { runProviderCommand } from "./commands/provider-cmd.mjs";export async function runCliCommand(command, argv, context = {}) {if (command === "doctor") {@@ -15,5 +20,25 @@ export async function runCliCommand(command, argv, context = {}) {return runSetupCommand(argv, context);}+ if (command === "config") {+ return runConfigCommand(argv);+ }++ if (command === "status") {+ return runStatusCommand(argv);+ }++ if (command === "logs") {+ return runLogsCommand(argv);+ }++ if (command === "update") {+ return runUpdateCommand(argv);+ }++ if (command === "provider") {+ return runProviderCommand(argv);+ }+throw new Error(`Unknown CLI command: ${command}`);}diff --git a/bin/cli/io.mjs b/bin/cli/io.mjsindex e131ba4ac0..97b419dc77 100644--- a/bin/cli/io.mjs+++ b/bin/cli/io.mjs@@ -54,3 +54,7 @@ export function printSuccess(message) {export function printInfo(message) {console.log(`\x1b[2m${message}\x1b[0m`);}++export function printError(message) {+ console.log(`\x1b[31m✖ ${message}\x1b[0m`);+}diff --git a/bin/omniroute.mjs b/bin/omniroute.mjsindex 1ce5ca86f7..54febbffc1 100644--- a/bin/omniroute.mjs+++ b/bin/omniroute.mjs@@ -79,7 +79,16 @@ loadEnvFile();const args = process.argv.slice(2);const command = args[0];-const CLI_COMMANDS = new Set(["doctor", "providers", "setup"]);+const CLI_COMMANDS = new Set([+ "doctor",+ "providers",+ "setup",+ "config",+ "status",+ "logs",+ "update",+ "provider",+]);if (CLI_COMMANDS.has(command)) {try {@@ -196,11 +205,23 @@ if (args.includes("--help") || args.includes("-h")) {omniroute providers available --search openaiomniroute providers available --category api-keyomniroute providers list- omniroute providers test <id|name>- omniroute providers test-all- omniroute providers validate-- \x1b[1mAfter starting:\x1b[0m+omniroute providers test <id|name>+ omniroute providers test-all+ omniroute providers validate++ \x1b[1mCLI Tools:\x1b[0m+ omniroute config list List CLI tool configuration status+ omniroute config get <tool> Show config for a specific tool+ omniroute config set <tool> Write config for a tool+ omniroute config validate <tool> Validate config without writing+ omniroute status Offline status dashboard+ omniroute logs [--follow] [--filter] Stream usage logs+ omniroute update [--check] [--dry-run] Check or apply OmniRoute update+ omniroute provider add <name> Add a provider connection+ omniroute provider list List configured providers+ omniroute provider test <name|id> Test a provider connection++ \x1b[1mAfter starting:\x1b[0mDashboard: http://localhost:<dashboard-port>API: http://localhost:<api-port>/v1diff --git a/docs/AUTO-COMBO.md b/docs/AUTO-COMBO.mdnew file mode 100644index 0000000000..c042204b81--- /dev/null+++ b/docs/AUTO-COMBO.md@@ -0,0 +1,134 @@+# OmniRoute Auto-Combo Engine++> Self-managing model chains with adaptive scoring + zero-config auto-routing++## Zero-Config Auto-Routing (`auto/` prefix)++> **NEW:** No combo creation required. Use `auto/` prefix directly in any client.++### Quick Examples++| Model ID | Variant | Behavior |+| -------------- | ------- | ------------------------------------------------------------------------ |+| `auto` | default | All connected providers, LKGP strategy, balanced weights |+| `auto/coding` | coding | Quality-first weights, suitable for code generation |+| `auto/fast` | fast | Low-latency weighted selection |+| `auto/cheap` | cheap | Cost-optimized routing (lowest cost first) |+| `auto/offline` | offline | Favors providers with highest quota availability |+| `auto/smart` | smart | Quality-first + higher exploration rate (10%) for better model discovery |+| `auto/lkgp` | lkgp | Explicit LKGP (same as default `auto`) |++**How to use:**++```bash+# Any IDE or CLI tool that supports OpenAI format+Base URL: http://localhost:20128/v1+API Key: <your-endpoint-key>++# In your code/config, set model to:+model: "auto" # balanced default+model: "auto/coding" # best for coding tasks+model: "auto/fast" # fastest available+model: "auto/cheap" # cheapest per token+```++**What happens:**++1. OmniRoute detects `auto/` prefix in `src/sse/handlers/chat.ts`+2. Queries all **active provider connections** from the database+3. Filters to those with valid credentials (API key or OAuth token)+4. Determines the model per connection (`connection.defaultModel` or provider's first model)+5. Builds a **virtual combo** in-memory (not stored in DB)+6. Routes using the selected variant's weight profile + LKGP strategy++**Key properties:**++- ✅ **Always-on:** No toggle, no combo creation, no configuration needed+- ✅ **Dynamic:** Reflects current connected providers automatically+- ✅ **Session stickiness:** LKGP ensures last successful provider is prioritized+- ✅ **Multi-account aware:** Each provider connection becomes a separate candidate+- ✅ **No DB writes:** Virtual combo exists only for the request, zero persistence overhead++**Behind the scenes:**++```txt+Request: { model: "auto/coding" }+ ↓+src/sse/handlers/chat.ts detects prefix+ ↓+createVirtualAutoCombo('coding') → candidatePool from active connections+ ↓+handleComboChat (same engine as persisted combos)+ ↓+Auto-scoring selects best provider/model per request+```++**Implementation files:**++| File | Purpose |+| --------------------------------------------------------- | ----------------------------------------- |+| `open-sse/services/autoCombo/autoPrefix.ts` | Prefix parser (`parseAutoPrefix`) |+| `open-sse/services/autoCombo/virtualFactory.ts` | Creates virtual `AutoComboConfig` objects |+| `open-sse/services/autoCombo/providerRegistryAccessor.ts` | Test hook for mocking provider registry |+| `src/sse/handlers/chat.ts` | Integration: auto prefix short-circuit |+| `src/shared/constants/providers.ts` | `SYSTEM_PROVIDERS.auto` system entry |++## How It Works (Persisted Auto-Combos)++The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**:++| Factor | Weight | Description |+| :--------- | :----- | :---------------------------------------------- |+| Quota | 0.20 | Remaining capacity [0..1] |+| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 |+| CostInv | 0.20 | Inverse cost (cheaper = higher score) |+| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) |+| TaskFit | 0.10 | Model × task type fitness score |+| Stability | 0.10 | Low variance in latency/errors |++## Mode Packs++| Pack | Focus | Key Weight |+| :---------------------- | :----------- | :--------------- |+| 🚀 **Ship Fast** | Speed | latencyInv: 0.35 |+| 💰 **Cost Saver** | Economy | costInv: 0.40 |+| 🎯 **Quality First** | Best model | taskFit: 0.40 |+| 📡 **Offline Friendly** | Availability | quota: 0.40 |++## Self-Healing++- **Temporary exclusion**: Score < 0.2 → excluded for 5 min (progressive backoff, max 30 min)+- **Circuit breaker awareness**: OPEN → auto-excluded; HALF_OPEN → probe requests+- **Incident mode**: >50% OPEN → disable exploration, maximize stability+- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout++## Bandit Exploration++5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode.++## API++```bash+# Create auto-combo+curl -X POST http://localhost:20128/api/combos/auto \+ -H "Content-Type: application/json" \+ -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}'++# List auto-combos+curl http://localhost:20128/api/combos/auto+```++## Task Fitness++30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` → high coding score).++## Files++| File | Purpose |+| :------------------------------------------- | :------------------------------------ |+| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization |+| `open-sse/services/autoCombo/taskFitness.ts` | Model × task fitness lookup |+| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap |+| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode |+| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles |+| `src/app/api/combos/auto/route.ts` | REST API |diff --git a/docs/CLI-TOOLS.md b/docs/CLI-TOOLS.mdnew file mode 100644index 0000000000..b04aac3893--- /dev/null+++ b/docs/CLI-TOOLS.md@@ -0,0 +1,492 @@+# CLI Tools Setup Guide — OmniRoute++This guide explains how to install and configure all supported AI coding CLI tools+to use **OmniRoute** as the unified backend, giving you centralized key management,+cost tracking, model switching, and request logging across every tool.++---++## How It Works++```+Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot+ │+ ▼ (all point to OmniRoute)+ http://YOUR_SERVER:20128/v1+ │+ ▼ (OmniRoute routes to the right provider)+ Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ...+```++**Benefits:**++- One API key to manage all tools+- Cost tracking across all CLIs in the dashboard+- Model switching without reconfiguring every tool+- Works locally and on remote servers (VPS)++---++## Supported Tools (Dashboard Source of Truth)++The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`.+Current list (v3.0.0-rc.16):++| Tool | ID | Command | Setup Mode | Install Method |+| ------------------ | ------------- | ---------- | ---------- | -------------- |+| **Claude Code** | `claude` | `claude` | env | npm |+| **OpenAI Codex** | `codex` | `codex` | custom | npm |+| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI |+| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI |+| **Cursor** | `cursor` | app | guide | desktop app |+| **Cline** | `cline` | `cline` | custom | npm |+| **Kilo Code** | `kilo` | `kilocode` | custom | npm |+| **Continue** | `continue` | extension | guide | VS Code |+| **Antigravity** | `antigravity` | internal | mitm | OmniRoute |+| **GitHub Copilot** | `copilot` | extension | custom | VS Code |+| **OpenCode** | `opencode` | `opencode` | guide | npm |+| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI |+| **Qwen Code** | `qwen` | `qwen` | custom | npm |++### CLI fingerprint sync (Agents + Settings)++`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`.+This keeps provider IDs aligned with CLI cards and legacy IDs.++| CLI ID | Fingerprint Provider ID |+| ---------------------------------------------------------------------------------------------------- | ----------------------- |+| `kilo` | `kilocode` |+| `copilot` | `github` |+| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID |++Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`.++---++## Step 1 — Get an OmniRoute API Key++1. Open the OmniRoute dashboard → **API Manager** (`/dashboard/api-manager`)+2. Click **Create API Key**+3. Give it a name (e.g. `cli-tools`) and select all permissions+4. Copy the key — you'll need it for every CLI below++> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx`++---++## Step 2 — Install CLI Tools++All npm-based tools require Node.js 18+:++```bash+# Claude Code (Anthropic)+npm install -g @anthropic-ai/claude-code++# OpenAI Codex+npm install -g @openai/codex++# OpenCode+npm install -g opencode-ai++# Cline+npm install -g cline++# KiloCode+npm install -g kilocode++# Kiro CLI (Amazon — requires curl + unzip)+apt-get install -y unzip # on Debian/Ubuntu+curl -fsSL https://cli.kiro.dev/install | bash+export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc+```++**Verify:**++```bash+claude --version # 2.x.x+codex --version # 0.x.x+opencode --version # x.x.x+cline --version # 2.x.x+kilocode --version # x.x.x (or: kilo --version)+kiro-cli --version # 1.x.x+```++---++## Step 3 — Set Global Environment Variables++Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`:++```bash+# OmniRoute Universal Endpoint+export OPENAI_BASE_URL="http://localhost:20128/v1"+export OPENAI_API_KEY="sk-your-omniroute-key"+export ANTHROPIC_BASE_URL="http://localhost:20128"+export ANTHROPIC_AUTH_TOKEN="sk-your-omniroute-key"+export GEMINI_BASE_URL="http://localhost:20128/v1"+export GEMINI_API_KEY="sk-your-omniroute-key"+```++> For a **remote server** replace `localhost:20128` with the server IP or domain,+> e.g. `http://192.168.0.15:20128`.++---++## Step 4 — Configure Each Tool++### Claude Code++```bash+# Create ~/.claude/settings.json:+mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF+{+ "env": {+ "ANTHROPIC_BASE_URL": "http://localhost:20128",+ "ANTHROPIC_AUTH_TOKEN": "sk-your-omniroute-key"+ }+}+EOF+```++Use the unified Anthropic gateway root for Claude Code. Do not append `/v1` here.++**Test:** `claude "say hello"`++---++### OpenAI Codex++```bash+mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF+model: auto+apiKey: sk-your-omniroute-key+apiBaseUrl: http://localhost:20128/v1+EOF+```++**Test:** `codex "what is 2+2?"`++---++### OpenCode++```bash+mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF+[provider.openai]+base_url = "http://localhost:20128/v1"+api_key = "sk-your-omniroute-key"+EOF+```++**Test:** `opencode`++---++### Cline (CLI or VS Code)++**CLI mode:**++```bash+mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF+{+ "apiProvider": "openai",+ "openAiBaseUrl": "http://localhost:20128/v1",+ "openAiApiKey": "sk-your-omniroute-key"+}+EOF+```++**VS Code mode:**+Cline extension settings → API Provider: `OpenAI Compatible` → Base URL: `http://localhost:20128/v1`++Or use the OmniRoute dashboard → **CLI Tools → Cline → Apply Config**.++---++### KiloCode (CLI or VS Code)++**CLI mode:**++```bash+kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key+```++**VS Code settings:**++```json+{+ "kilo-code.openAiBaseUrl": "http://localhost:20128/v1",+ "kilo-code.apiKey": "sk-your-omniroute-key"+}+```++Or use the OmniRoute dashboard → **CLI Tools → KiloCode → Apply Config**.++---++### Continue (VS Code Extension)++Edit `~/.continue/config.yaml`:++```yaml+models:+ - name: OmniRoute+ provider: openai+ model: auto+ apiBase: http://localhost:20128/v1+ apiKey: sk-your-omniroute-key+ default: true+```++Restart VS Code after editing.++---++### Kiro CLI (Amazon)++```bash+# Login to your AWS/Kiro account:+kiro-cli login++# The CLI uses its own auth — OmniRoute is not needed as backend for Kiro CLI itself.+# Use kiro-cli alongside OmniRoute for other tools.+kiro-cli status+```++---++### Qwen Code (Alibaba)++Qwen Code supports OpenAI-compatible API endpoints via environment variables or `settings.json`.++**Option 1: Environment variables (`~/.qwen/.env`)**++```bash+mkdir -p ~/.qwen && cat > ~/.qwen/.env << EOF+OPENAI_API_KEY="sk-your-omniroute-key"+OPENAI_BASE_URL="http://localhost:20128/v1"+OPENAI_MODEL="auto"+EOF+```++**Option 2: `settings.json` with model providers**++```json+// ~/.qwen/settings.json+{+ "env": {+ "OPENAI_API_KEY": "sk-your-omniroute-key",+ "OPENAI_BASE_URL": "http://localhost:20128/v1"+ },+ "modelProviders": {+ "openai": [+ {+ "id": "omniroute-default",+ "name": "OmniRoute (Auto)",+ "envKey": "OPENAI_API_KEY",+ "baseUrl": "http://localhost:20128/v1"+ }+ ]+ }+}+```++**Option 3: Inline CLI flags**++```bash+OPENAI_BASE_URL="http://localhost:20128/v1" \+OPENAI_API_KEY="sk-your-omniroute-key" \+OPENAI_MODEL="auto" \+qwen+```++> For a **remote server** replace `localhost:20128` with the server IP or domain.++**Test:** `qwen "say hello"`++### Cursor (Desktop App)++> **Note:** Cursor routes requests through its cloud. For OmniRoute integration,+> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL.++Via GUI: **Settings → Models → OpenAI API Key**++- Base URL: `https://your-domain.com/v1`+- API Key: your OmniRoute key++---++## Dashboard Auto-Configuration++The OmniRoute dashboard automates configuration for most tools:++1. Go to `http://localhost:20128/dashboard/cli-tools`+2. Expand any tool card+3. Select your API key from the dropdown+4. Click **Apply Config** (if tool is detected as installed)+5. Or copy the generated config snippet manually++---++## Built-in Agents: Droid & OpenClaw++**Droid** and **OpenClaw** are AI agents built directly into OmniRoute — no installation needed.+They run as internal routes and use OmniRoute's model routing automatically.++- Access: `http://localhost:20128/dashboard/agents`+- Configure: same combos and providers as all other tools+- No API key or CLI install required++---++## Available API Endpoints++| Endpoint | Description | Use For |+| -------------------------- | ----------------------------- | --------------------------- |+| `/v1/chat/completions` | Standard chat (all providers) | All modern tools |+| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows |+| `/v1/completions` | Legacy text completions | Older tools using `prompt:` |+| `/v1/embeddings` | Text embeddings | RAG, search |+| `/v1/images/generations` | Image generation | GPT-Image, Flux, etc. |+| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS |+| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI |++### CLI Tools API (New in v3.8)++| Endpoint | Method | Description |+| ------------------------------- | ------ | ------------------------------------------------ |+| `/api/cli-tools/detect` | GET | Detect all installed CLI tools and config status |+| `/api/cli-tools/detect?tool=ID` | GET | Detect a specific tool by ID |+| `/api/cli-tools/config` | GET | List generated configs for all tools |+| `/api/cli-tools/config` | POST | Generate config for a specific tool |+| `/api/cli-tools/apply` | POST | Apply config to a tool (with backup) |++---++## CLI Commands Reference (New in v3.8)++### `omniroute config`++Manage CLI tool configurations directly from the terminal.++```bash+omniroute config list # List all tools and config status+omniroute config get <tool> # Show config for a specific tool+omniroute config set <tool> \ # Generate and write config+ --api-key sk-your-key \+ [--base-url http://localhost:20128/v1] \+ [--model auto]+omniroute config validate <tool> # Validate config without writing+```++**Options:** `--base-url`, `--api-key`, `--model`, `--json`, `--non-interactive`, `--yes`, `--help`++### `omniroute status`++Show offline status dashboard with version, database, and tool info.++```bash+omniroute status # Human-readable status+omniroute status --json # JSON output+omniroute status --verbose # Include tool detection details+```++### `omniroute logs`++Stream usage logs from the API endpoint.++```bash+omniroute logs # Fetch last 100 log lines+omniroute logs --follow # Stream in real-time+omniroute logs --filter error,warn # Filter by level+omniroute logs --lines 500 # Fetch more lines+omniroute logs --base-url http://localhost:20128+```++**Options:** `--follow`, `--filter`, `--lines`, `--timeout`, `--base-url`, `--json`, `--help`++### `omniroute update`++Check for or apply OmniRoute updates.++```bash+omniroute update --check # Check for updates only+omniroute update --dry-run # Preview update without applying+omniroute update --yes # Apply update without prompt+omniroute update --no-backup # Skip backup creation+```++**Options:** `--check`, `--dry-run`, `--backup`, `--no-backup`, `--yes`, `--help`++### `omniroute provider`++Manage provider connections from the CLI.++```bash+omniroute provider add openai --api-key sk-xxx # Add a provider+omniroute provider list # List all providers+omniroute provider remove <name|id> # Remove a provider+omniroute provider test <name|id> # Test connectivity+omniroute provider default <name|id> # Set default provider+```++**Options:** `--provider`, `--api-key`, `--provider-name`, `--default-model`, `--base-url`, `--json`, `--yes`, `--help`++---++## Quick Setup Script (One Command)++Set up all CLI tools and configure for OmniRoute:++```bash+OMNIROUTE_URL="http://localhost:20128/v1"+OMNIROUTE_ANTHROPIC_URL="http://localhost:20128"+OMNIROUTE_KEY="sk-your-omniroute-key"++npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode @qwen-code/qwen-code++# Kiro CLI+apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash++# Write configs+mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue++cat > ~/.claude/settings.json <<< "{\"env\":{\"ANTHROPIC_BASE_URL\":\"$OMNIROUTE_ANTHROPIC_URL\",\"ANTHROPIC_AUTH_TOKEN\":\"$OMNIROUTE_KEY\"}}"+cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL"+cat >> ~/.bashrc << EOF+export OPENAI_BASE_URL="$OMNIROUTE_URL"+export OPENAI_API_KEY="$OMNIROUTE_KEY"+export ANTHROPIC_BASE_URL="$OMNIROUTE_ANTHROPIC_URL"+export ANTHROPIC_AUTH_TOKEN="$OMNIROUTE_KEY"+EOF++source ~/.bashrc+echo "✅ All CLIs installed and configured for OmniRoute"+```++```bash+# Install all CLIs and configure for OmniRoute (replace with your key and server URL)+OMNIROUTE_URL="http://localhost:20128/v1"+OMNIROUTE_ANTHROPIC_URL="http://localhost:20128"+OMNIROUTE_KEY="sk-your-omniroute-key"++npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode @qwen-code/qwen-code++# Kiro CLI+apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash++# Write configs+mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue++cat > ~/.claude/settings.json <<< "{\"env\":{\"ANTHROPIC_BASE_URL\":\"$OMNIROUTE_ANTHROPIC_URL\",\"ANTHROPIC_AUTH_TOKEN\":\"$OMNIROUTE_KEY\"}}"+cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL"+cat >> ~/.bashrc << EOF+export OPENAI_BASE_URL="$OMNIROUTE_URL"+export OPENAI_API_KEY="$OMNIROUTE_KEY"+export ANTHROPIC_BASE_URL="$OMNIROUTE_ANTHROPIC_URL"+export ANTHROPIC_AUTH_TOKEN="$OMNIROUTE_KEY"+EOF++source ~/.bashrc+echo "✅ All CLIs installed and configured for OmniRoute"+```diff --git a/docs/guides/SETUP_GUIDE.md b/docs/guides/SETUP_GUIDE.mdindex f3fb9af3ac..4031ea6160 100644--- a/docs/guides/SETUP_GUIDE.md+++ b/docs/guides/SETUP_GUIDE.md@@ -91,16 +91,21 @@ Combined with env vars (`INITIAL_PASSWORD`, `OMNIROUTE_WS_BRIDGE_SECRET`, etc.),### CLI Options-| Command | Description |-| ----------------------- | ----------------------------------------------------------- |-| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |-| `omniroute setup` | Guided CLI onboarding for password and first provider |-| `omniroute doctor` | Run local health checks without starting the server |-| `omniroute providers` | Discover, list, validate, and test providers from CLI |-| `omniroute --port 3000` | Set canonical/API port to 3000 |-| `omniroute --mcp` | Start MCP server (stdio transport) |-| `omniroute --no-open` | Don't auto-open browser |-| `omniroute --help` | Show help |+| Command | Description |+| ----------------------- | -------------------------------------------------------------- |+| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |+| `omniroute setup` | Guided CLI onboarding for password and first provider |+| `omniroute doctor` | Run local health checks without starting the server |+| `omniroute providers` | Discover, list, validate, and test providers from CLI |+| `omniroute config` | CLI tool configuration — list, get, set, validate configs |+| `omniroute status` | Offline status dashboard — version, DB, tools, config |+| `omniroute logs` | Stream usage logs from the API (supports `--follow`) |+| `omniroute update` | Check for or apply OmniRoute updates |+| `omniroute provider` | Manage provider connections — add, list, remove, test, default |+| `omniroute --port 3000` | Set canonical/API port to 3000 |+| `omniroute --mcp` | Start MCP server (stdio transport) |+| `omniroute --no-open` | Don't auto-open browser |+| `omniroute --help` | Show help |Headless setup can be scripted with flags or environment variables:diff --git a/package.json b/package.jsonindex d639f8853e..d9fc1076f4 100644--- a/package.json+++ b/package.json@@ -10,6 +10,8 @@"files": ["bin/","app/",+ "src/lib/cli-helper/",+ "@omniroute/","open-sse/mcp-server/index.ts","open-sse/mcp-server/server.ts","open-sse/mcp-server/httpTransport.ts",diff --git a/src/app/(dashboard)/dashboard/settings/components/RoutingTab.tsx b/src/app/(dashboard)/dashboard/settings/components/RoutingTab.tsxindex 82f5110939..23b1c52259 100644--- a/src/app/(dashboard)/dashboard/settings/components/RoutingTab.tsx+++ b/src/app/(dashboard)/dashboard/settings/components/RoutingTab.tsx@@ -296,8 +296,16 @@ export default function RoutingTab() {}}disabled={loading || forced}aria-pressed={checked}+<<<<<<< HEADaria-disabled={forced || undefined}title={titleText}+=======+ title={+ checked+ ? t("disableFingerprintTitle", { provider: label })+ : t("enableFingerprintTitle", { provider: label })+ }+>>>>>>> a10ef5ee (feat(auto): complete zero-config auto-routing feature)className={`flex items-start gap-3 rounded-lg border p-3 text-left transition-all ${checked? "border-indigo-500/50 bg-indigo-500/5 ring-1 ring-indigo-500/20"diff --git a/src/app/api/cli-tools/apply/route.ts b/src/app/api/cli-tools/apply/route.tsnew file mode 100644index 0000000000..8547401b39--- /dev/null+++ b/src/app/api/cli-tools/apply/route.ts@@ -0,0 +1,82 @@+import { NextResponse } from "next/server";+import { requireCliToolsAuth } from "@/lib/api/requireCliToolsAuth";+import fs from "node:fs";+import path from "node:path";+import os from "node:os";+import { generateConfig } from "@/lib/cli-helper/config-generator";++const TOOL_CONFIG_PATHS: Record<string, string> = {+ claude: path.join(os.homedir(), ".claude", "settings.json"),+ codex: path.join(os.homedir(), ".codex", "config.yaml"),+ opencode: path.join(os.homedir(), ".config", "opencode", "opencode.json"),+ cline: path.join(os.homedir(), ".cline", "data", "globalState.json"),+ kilocode: path.join(os.homedir(), ".config", "kilocode", "settings.json"),+ continue: path.join(os.homedir(), ".continue", "config.yaml"),+};++function ensureBackup(configPath: string): string | null {+ if (!fs.existsSync(configPath)) return null;+ const backupDir = path.join(path.dirname(configPath), ".omniroute.bak");+ if (!fs.existsSync(backupDir)) fs.mkdirSync(backupDir, { recursive: true });+ const backupPath = path.join(backupDir, path.basename(configPath) + ".bak");+ fs.copyFileSync(configPath, backupPath);+ return backupPath;+}++// POST /api/cli-tools/apply - Apply config for a specific tool+export async function POST(request: Request) {+ const authError = await requireCliToolsAuth(request);+ if (authError) return authError;++ try {+ const body = await request.json();+ const { toolId, baseUrl, apiKey, model, dryRun } = body;++ if (!toolId) {+ return NextResponse.json({ error: "toolId is required" }, { status: 400 });+ }+ if (!apiKey) {+ return NextResponse.json({ error: "apiKey is required" }, { status: 400 });+ }++ const result = await generateConfig(toolId, {+ baseUrl: baseUrl || "http://localhost:20128/v1",+ apiKey,+ model,+ });++ if (!result.success) {+ return NextResponse.json({ error: result.error }, { status: 400 });+ }++ if (dryRun) {+ return NextResponse.json({+ dryRun: true,+ configPath: result.configPath,+ content: result.content,+ });+ }++ const configPath = TOOL_CONFIG_PATHS[toolId];+ if (!configPath) {+ return NextResponse.json({ error: `Unknown tool: ${toolId}` }, { status: 400 });+ }++ const backupPath = ensureBackup(configPath);++ const dir = path.dirname(configPath);+ if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });++ fs.writeFileSync(configPath, result.content!, "utf-8");++ return NextResponse.json({+ success: true,+ configPath,+ backupPath,+ content: result.content,+ });+ } catch (error) {+ console.log("Error applying config:", error);+ return NextResponse.json({ error: "Failed to apply config" }, { status: 500 });+ }+}diff --git a/src/app/api/cli-tools/config/route.ts b/src/app/api/cli-tools/config/route.tsnew file mode 100644index 0000000000..35f74ef613--- /dev/null+++ b/src/app/api/cli-tools/config/route.ts@@ -0,0 +1,61 @@+import { NextResponse } from "next/server";+import { requireCliToolsAuth } from "@/lib/api/requireCliToolsAuth";+import { generateConfig, generateAllConfigs } from "@/lib/cli-helper/config-generator";++// GET /api/cli-tools/config - List generated configs for all tools+export async function GET(request: Request) {+ const authError = await requireCliToolsAuth(request);+ if (authError) return authError;++ const { searchParams } = new URL(request.url);+ const baseUrl = searchParams.get("baseUrl") || "http://localhost:20128/v1";+ const apiKey = searchParams.get("apiKey") || "";++ if (!apiKey) {+ return NextResponse.json({ error: "API key is required" }, { status: 400 });+ }++ try {+ const results = await generateAllConfigs({ baseUrl, apiKey });+ return NextResponse.json({ configs: results });+ } catch (error) {+ console.log("Error generating configs:", error);+ return NextResponse.json({ error: "Failed to generate configs" }, { status: 500 });+ }+}++// POST /api/cli-tools/config - Generate config for a specific tool+export async function POST(request: Request) {+ const authError = await requireCliToolsAuth(request);+ if (authError) return authError;++ try {+ const body = await request.json();+ const { toolId, baseUrl, apiKey, model } = body;++ if (!toolId) {+ return NextResponse.json({ error: "toolId is required" }, { status: 400 });+ }+ if (!apiKey) {+ return NextResponse.json({ error: "apiKey is required" }, { status: 400 });+ }++ const result = await generateConfig(toolId, {+ baseUrl: baseUrl || "http://localhost:20128/v1",+ apiKey,+ model,+ });++ if (!result.success) {+ return NextResponse.json({ error: result.error }, { status: 400 });+ }++ return NextResponse.json({+ configPath: result.configPath,+ content: result.content,+ });+ } catch (error) {+ console.log("Error generating config:", error);+ return NextResponse.json({ error: "Failed to generate config" }, { status: 500 });+ }+}diff --git a/src/app/api/cli-tools/detect/route.ts b/src/app/api/cli-tools/detect/route.tsnew file mode 100644index 0000000000..58f0a28e97--- /dev/null+++ b/src/app/api/cli-tools/detect/route.ts@@ -0,0 +1,28 @@+import { NextResponse } from "next/server";+import { requireCliToolsAuth } from "@/lib/api/requireCliToolsAuth";+import { detectAllTools, detectTool } from "@/lib/cli-helper/tool-detector";++// GET /api/cli-tools/detect - Detect all installed CLI tools+export async function GET(request: Request) {+ const authError = await requireCliToolsAuth(request);+ if (authError) return authError;++ const { searchParams } = new URL(request.url);+ const toolId = searchParams.get("tool");++ try {+ if (toolId) {+ const tool = await detectTool(toolId);+ if (!tool) {+ return NextResponse.json({ error: `Unknown tool: ${toolId}` }, { status: 400 });+ }+ return NextResponse.json(tool);+ }++ const tools = await detectAllTools();+ return NextResponse.json({ tools });+ } catch (error) {+ console.log("Error detecting tools:", error);+ return NextResponse.json({ error: "Failed to detect tools" }, { status: 500 });+ }+}diff --git a/src/lib/cli-helper/config-generator/claude.ts b/src/lib/cli-helper/config-generator/claude.tsnew file mode 100644index 0000000000..488f72eeaa--- /dev/null+++ b/src/lib/cli-helper/config-generator/claude.ts@@ -0,0 +1,21 @@+import path from "node:path";+import os from "node:os";++const CONFIG_PATH = path.join(os.homedir(), ".claude", "settings.json");++export function generateClaudeConfig(options: {+ baseUrl: string;+ apiKey: string;+ model?: string;+}): string {+ const base = options.baseUrl.replace(/\/+$/, "").replace(/\/v1$/, "");+ const model = options.model || "claude-3-5-sonnet-20241022";++ const config = {+ baseUrl: `${base}/v1`,+ authToken: options.apiKey,+ models: [{ id: model }],+ };++ return JSON.stringify(config, null, 2);+}diff --git a/src/lib/cli-helper/config-generator/cline.ts b/src/lib/cli-helper/config-generator/cline.tsnew file mode 100644index 0000000000..5c5bc78765--- /dev/null+++ b/src/lib/cli-helper/config-generator/cline.ts@@ -0,0 +1,19 @@+import path from "node:path";+import os from "node:os";++const CONFIG_PATH = path.join(os.homedir(), ".cline", "data", "globalState.json");++export function generateClineConfig(options: {+ baseUrl: string;+ apiKey: string;+ model?: string;+}): string {+ const base = options.baseUrl.replace(/\/+$/, "").replace(/\/v1$/, "");++ const config = {+ openAiBaseUrl: `${base}/v1`,+ openAiApiKey: options.apiKey,+ };++ return JSON.stringify(config, null, 2);+}diff --git a/src/lib/cli-helper/config-generator/codex.ts b/src/lib/cli-helper/config-generator/codex.tsnew file mode 100644index 0000000000..4ec669e483--- /dev/null+++ b/src/lib/cli-helper/config-generator/codex.ts@@ -0,0 +1,30 @@+import path from "node:path";+import os from "node:os";++let yaml: typeof import("js-yaml") | null = null;+async function loadYaml() {+ if (!yaml) {+ yaml = await import("js-yaml");+ }+ return yaml;+}++const CONFIG_PATH = path.join(os.homedir(), ".codex", "config.yaml");++export async function generateCodexConfig(options: {+ baseUrl: string;+ apiKey: string;+ model?: string;+}): Promise<string> {+ const y = await loadYaml();+ const base = options.baseUrl.replace(/\/+$/, "").replace(/\/v1$/, "");++ const config = {+ openai: {+ api_key: options.apiKey,+ base_url: `${base}/v1`,+ },+ };++ return y.dump(config, { lineWidth: -1 });+}diff --git a/src/lib/cli-helper/config-generator/continue.ts b/src/lib/cli-helper/config-generator/continue.tsnew file mode 100644index 0000000000..8eedb4afcf--- /dev/null+++ b/src/lib/cli-helper/config-generator/continue.ts@@ -0,0 +1,33 @@+import path from "node:path";+import os from "node:os";++let yaml: typeof import("js-yaml") | null = null;+async function loadYaml() {+ if (!yaml) {+ yaml = await import("js-yaml");+ }+ return yaml;+}++const CONFIG_PATH = path.join(os.homedir(), ".continue", "config.yaml");++export async function generateContinueConfig(options: {+ baseUrl: string;+ apiKey: string;+ model?: string;+}): Promise<string> {+ const y = await loadYaml();+ const base = options.baseUrl.replace(/\/+$/, "").replace(/\/v1$/, "");++ const config = {+ models: [+ {+ title: "OmniRoute",+ apiKey: options.apiKey,+ apiBase: `${base}/v1`,+ },+ ],+ };++ return y.dump(config, { lineWidth: -1 });+}diff --git a/src/lib/cli-helper/config-generator/index.ts b/src/lib/cli-helper/config-generator/index.tsnew file mode 100644index 0000000000..9431eaa12d--- /dev/null+++ b/src/lib/cli-helper/config-generator/index.ts@@ -0,0 +1,95 @@+import path from "node:path";+import os from "node:os";++export interface GenerateOptions {+ baseUrl: string;+ apiKey: string;+ model?: string;+}++export interface GenerateResult {+ success: boolean;+ configPath: string;+ content?: string;+ error?: string;+}++function validateBaseUrl(url: string): boolean {+ try {+ const u = new URL(url);+ return u.protocol === "http:" || u.protocol === "https:";+ } catch {+ return false;+ }+}++function expandHome(p: string): string {+ const home = os.homedir();+ return p.replace(/^~\//, home + "/");+}++const TOOL_CONFIG_PATHS: Record<string, string> = {+ claude: path.join(os.homedir(), ".claude", "settings.json"),+ codex: path.join(os.homedir(), ".codex", "config.yaml"),+ opencode: path.join(os.homedir(), ".config", "opencode", "opencode.json"),+ cline: path.join(os.homedir(), ".cline", "data", "globalState.json"),+ kilocode: path.join(os.homedir(), ".config", "kilocode", "settings.json"),+ continue: path.join(os.homedir(), ".continue", "config.yaml"),+};++async function importGenerator(toolId: string) {+ const generators: Record<string, { module: string; export: string }> = {+ claude: { module: "./claude.js", export: "generateClaudeConfig" },+ codex: { module: "./codex.js", export: "generateCodexConfig" },+ opencode: { module: "./opencode.js", export: "generateOpencodeConfig" },+ cline: { module: "./cline.js", export: "generateClineConfig" },+ kilocode: { module: "./kilocode.js", export: "generateKilocodeConfig" },+ continue: { module: "./continue.js", export: "generateContinueConfig" },+ };++ const gen = generators[toolId];+ if (!gen) return null;+ const mod = await import(gen.module);+ return { generate: mod[gen.export] };+}++export async function generateConfig(+ toolId: string,+ options: GenerateOptions+): Promise<GenerateResult> {+ if (!validateBaseUrl(options.baseUrl)) {+ return {+ success: false,+ configPath: "",+ error: "Invalid baseUrl: must be an absolute HTTP(S) URL",+ };+ }++ if (!options.apiKey || options.apiKey.trim().length === 0) {+ return { success: false, configPath: "", error: "API key is required" };+ }++ try {+ const mod = await importGenerator(toolId);+ if (!mod) {+ return { success: false, configPath: "", error: `Unknown tool: ${toolId}` };+ }+ const content = await mod.generate(options);+ const configPath = TOOL_CONFIG_PATHS[toolId] || "";+ return { success: true, configPath, content };+ } catch (err) {+ const msg = err instanceof Error ? err.message : String(err);+ return { success: false, configPath: "", error: `Generation failed: ${msg}` };+ }+}++export async function generateAllConfigs(options: GenerateOptions): Promise<GenerateResult[]> {+ const toolIds = ["claude", "codex", "opencode", "cline", "kilocode", "continue"] as const;+ const results = await Promise.allSettled(toolIds.map((id) => generateConfig(id, options)));++ return results.map((r) =>+ r.status === "fulfilled"+ ? r.value+ : { success: false, configPath: "", error: r.reason?.message || "Unknown error" }+ );+}diff --git a/src/lib/cli-helper/config-generator/kilocode.ts b/src/lib/cli-helper/config-generator/kilocode.tsnew file mode 100644index 0000000000..8c43dcd407--- /dev/null+++ b/src/lib/cli-helper/config-generator/kilocode.ts@@ -0,0 +1,19 @@+import path from "node:path";+import os from "node:os";++const CONFIG_PATH = path.join(os.homedir(), ".config", "kilocode", "settings.json");++export function generateKilocodeConfig(options: {+ baseUrl: string;+ apiKey: string;+ model?: string;+}): string {+ const base = options.baseUrl.replace(/\/+$/, "").replace(/\/v1$/, "");++ const config = {+ apiKey: options.apiKey,+ baseUrl: `${base}/v1`,+ };++ return JSON.stringify(config, null, 2);+}diff --git a/src/lib/cli-helper/config-generator/opencode.ts b/src/lib/cli-helper/config-generator/opencode.tsnew file mode 100644index 0000000000..b17214dac7--- /dev/null+++ b/src/lib/cli-helper/config-generator/opencode.ts@@ -0,0 +1,21 @@+import path from "node:path";+import os from "node:os";++const CONFIG_PATH = path.join(os.homedir(), ".config", "opencode", "opencode.json");++export function generateOpencodeConfig(options: {+ baseUrl: string;+ apiKey: string;+ model?: string;+}): string {+ const base = options.baseUrl.replace(/\/+$/, "").replace(/\/v1$/, "");++ const config = {+ provider: "omniroute",+ baseURL: `${base}/v1`,+ apiKey: options.apiKey,+ model: options.model || "opencode",+ };++ return JSON.stringify(config, null, 2);+}diff --git a/src/lib/cli-helper/doctor/checks.ts b/src/lib/cli-helper/doctor/checks.tsnew file mode 100644index 0000000000..353d0e6026--- /dev/null+++ b/src/lib/cli-helper/doctor/checks.ts@@ -0,0 +1,41 @@+import path from "node:path";+import os from "node:os";++export interface DoctorCheckResult {+ name: string;+ status: "ok" | "warn" | "fail";+ message: string;+ details: Record<string, unknown>;+}++export async function collectCliToolChecks(): Promise<DoctorCheckResult[]> {+ const { detectAllTools } = await import("../tool-detector.js");+ const tools = await detectAllTools();++ return tools.map((tool) => {+ if (!tool.installed) {+ return {+ name: `CLI: ${tool.name}`,+ status: "warn" as const,+ message: `${tool.name} not installed`,+ details: { id: tool.id, installed: false },+ };+ }++ if (!tool.configured) {+ return {+ name: `CLI: ${tool.name}`,+ status: "warn" as const,+ message: `${tool.name} not configured for OmniRoute`,+ details: { id: tool.id, configured: false },+ };+ }++ return {+ name: `CLI: ${tool.name}`,+ status: "ok" as const,+ message: `${tool.name} configured`,+ details: { id: tool.id, configured: true },+ };+ });+}diff --git a/src/lib/cli-helper/log-streamer.ts b/src/lib/cli-helper/log-streamer.tsnew file mode 100644index 0000000000..9a4c237fed--- /dev/null+++ b/src/lib/cli-helper/log-streamer.ts@@ -0,0 +1,79 @@+import os from "node:os";+import path from "node:path";++export interface LogStreamOptions {+ baseUrl?: string;+ filters?: string[];+ follow?: boolean;+ timeout?: number;+}++export interface LogStream {+ stream: ReadableStream<Uint8Array>;+ stop: () => void;+}++export function createLogStream(options: LogStreamOptions = {}): LogStream {+ const baseUrl = options.baseUrl || "http://localhost:20128";+ const filters = options.filters || [];+ const follow = options.follow ?? false;+ const timeout = options.timeout || 30000;++ const controller = new AbortController();+ const { signal } = controller;++ const stream = new ReadableStream<Uint8Array>({+ async start(controller) {+ let url = `${baseUrl}/api/cli-tools/logs?follow=${follow}`;+ if (filters.length > 0) {+ url += `&filter=${encodeURIComponent(filters.join(","))}`;+ }++ const timeoutId = setTimeout(() => {+ if (follow) return; // Don't timeout follow mode+ controller.error(new Error(`Log stream timed out after ${timeout}ms`));+ }, timeout);++ try {+ const response = await fetch(url, { signal });++ if (!response.ok) {+ controller.error(new Error(`HTTP ${response.status}: ${response.statusText}`));+ clearTimeout(timeoutId);+ return;+ }++ if (!response.body) {+ controller.error(new Error("Response body is null"));+ clearTimeout(timeoutId);+ return;+ }++ const reader = response.body.getReader();++ while (true) {+ const { done, value } = await reader.read();+ if (done) break;+ if (signal.aborted) break;+ controller.enqueue(value);+ }++ controller.close();+ clearTimeout(timeoutId);+ } catch (err) {+ if (signal.aborted) return; // Expected stop+ controller.error(err instanceof Error ? err : new Error(String(err)));+ clearTimeout(timeoutId);+ }+ },++ cancel() {+ controller.abort();+ },+ });++ return {+ stream,+ stop: () => controller.abort(),+ };+}diff --git a/src/lib/cli-helper/tool-detector.ts b/src/lib/cli-helper/tool-detector.tsnew file mode 100644index 0000000000..7b48f46585--- /dev/null+++ b/src/lib/cli-helper/tool-detector.ts@@ -0,0 +1,105 @@+import os from "node:os";+import path from "node:path";+import { execFile } from "node:child_process";+import { promisify } from "node:util";++const execFileAsync = promisify(execFile);++export interface DetectedTool {+ id: string;+ name: string;+ installed: boolean;+ version?: string;+ configPath: string;+ configured: boolean;+ configContents?: string;+}++const TOOLS = [+ { id: "claude", name: "Claude Code", configPath: "~/.claude/settings.json" },+ { id: "codex", name: "Codex CLI", configPath: "~/.codex/config.yaml" },+ { id: "opencode", name: "OpenCode", configPath: "~/.config/opencode/opencode.json" },+ { id: "cline", name: "Cline", configPath: "~/.cline/data/globalState.json" },+ { id: "kilocode", name: "Kilo Code", configPath: "~/.config/kilocode/settings.json" },+ { id: "continue", name: "Continue", configPath: "~/.continue/config.yaml" },+] as const;++const BINARY_NAMES: Record<string, string> = {+ claude: "claude",+ codex: "codex",+ opencode: "opencode",+ cline: "cline",+ kilocode: "kilocode",+ continue: "continue",+};++function expandHome(p: string): string {+ const home = os.homedir();+ return p.replace(/^~\//, home + "/");+}++function isConfigured(content: string, baseUrl: string): boolean {+ const normalized = baseUrl.replace(/\/+$/, "");+ return (+ content.includes(normalized) ||+ content.includes("localhost:20128") ||+ content.includes("OMNIROUTE_BASE_URL")+ );+}++async function detectBinary(name: string): Promise<{ installed: boolean; version?: string }> {+ const binary = BINARY_NAMES[name] || name;+ try {+ const { stdout } = await execFileAsync(binary, ["--version"], { timeout: 5000 });+ const version = stdout.trim().replace(/^v/, "");+ return { installed: true, version };+ } catch {+ try {+ // Try `which` as fallback+ const { stdout } = await execFileAsync("which", [binary], { timeout: 5000 });+ if (stdout.trim()) {+ return { installed: true };+ }+ } catch {}+ return { installed: false };+ }+}++async function readConfigFile(configPath: string): Promise<string | null> {+ try {+ const { readFileSync } = await import("node:fs");+ const expanded = expandHome(configPath);+ if (!expanded) return null;+ return readFileSync(expanded, "utf-8");+ } catch {+ return null;+ }+}++export async function detectTool(id: string): Promise<DetectedTool | null> {+ const tool = TOOLS.find((t) => t.id === id);+ if (!tool) return null;++ const { installed, version } = await detectBinary(tool.id);+ const configPath = expandHome(tool.configPath);+ const configContents = await readConfigFile(tool.configPath);+ const configured = !!configContents && isConfigured(configContents, "http://localhost:20128");++ return {+ id: tool.id,+ name: tool.name,+ installed,+ version,+ configPath,+ configured,+ configContents: configContents ?? undefined,+ };+}++export async function detectAllTools(): Promise<DetectedTool[]> {+ const results = await Promise.allSettled(TOOLS.map((t) => detectTool(t.id)));++ return results+ .filter((r) => r.status === "fulfilled" && r.value !== null)+ .map((r) => (r as PromiseFulfilledResult<DetectedTool>).value);+}diff --git a/src/shared/components/AutoRoutingBanner.test.tsx b/src/shared/components/AutoRoutingBanner.test.tsxnew file mode 100644index 0000000000..2249ef566e--- /dev/null+++ b/src/shared/components/AutoRoutingBanner.test.tsx@@ -0,0 +1,96 @@+// @vitest-environment jsdom+import React from "react";+import { act } from "react";+import { createRoot } from "react-dom/client";+import { afterEach, beforeEach, describe, expect, it } from "vitest";++const cleanupCallbacks: Array<() => void> = [];++function makeContainer(): HTMLElement {+ const container = document.createElement("div");+ document.body.appendChild(container);+ cleanupCallbacks.push(() => {+ container.remove();+ });+ return container;+}++describe("AutoRoutingBanner", () => {+ beforeEach(() => {+ (+ globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }+ ).IS_REACT_ACT_ENVIRONMENT = true;+ localStorage.clear();+ });++ afterEach(() => {+ while (cleanupCallbacks.length > 0) {+ cleanupCallbacks.pop()?.();+ }+ document.body.innerHTML = "";+ localStorage.clear();+ });++ it("renders banner on first mount", async () => {+ const { default: AutoRoutingBanner } = await import("./AutoRoutingBanner");+ const container = makeContainer();+ const root = createRoot(container);+ await act(async () => {+ root.render(<AutoRoutingBanner />);+ });+ expect(container.querySelector('[role="banner"]')).toBeTruthy();+ expect(container.textContent).toContain("Auto-Routing Active");+ });++ it("includes link to Combos page", async () => {+ const { default: AutoRoutingBanner } = await import("./AutoRoutingBanner");+ const container = makeContainer();+ const root = createRoot(container);+ await act(async () => {+ root.render(<AutoRoutingBanner />);+ });+ const link = container.querySelector('a[href="/dashboard/combos"]');+ expect(link).toBeTruthy();+ });++ it("can be dismissed by clicking close button", async () => {+ const { default: AutoRoutingBanner } = await import("./AutoRoutingBanner");+ const container = makeContainer();+ const root = createRoot(container);+ await act(async () => {+ root.render(<AutoRoutingBanner />);+ });+ expect(container.querySelector('[role="banner"]')).toBeTruthy();+ const closeButton = container.querySelector('button[aria-label="Dismiss auto-routing banner"]');+ expect(closeButton).toBeTruthy();+ await act(async () => {+ closeButton?.click();+ });+ expect(container.querySelector('[role="banner"]')).toBeFalsy();+ });++ it("persists dismissal to localStorage", async () => {+ const { default: AutoRoutingBanner } = await import("./AutoRoutingBanner");+ const container = makeContainer();+ const root = createRoot(container);+ await act(async () => {+ root.render(<AutoRoutingBanner />);+ });+ const closeButton = container.querySelector('button[aria-label="Dismiss auto-routing banner"]');+ await act(async () => {+ closeButton?.click();+ });+ expect(localStorage.getItem("auto-routing-banner-dismissed")).toBe("true");+ });++ it("remains hidden after dismissal on remount", async () => {+ localStorage.setItem("auto-routing-banner-dismissed", "true");+ const { default: AutoRoutingBanner } = await import("./AutoRoutingBanner");+ const container = makeContainer();+ const root = createRoot(container);+ await act(async () => {+ root.render(<AutoRoutingBanner />);+ });+ expect(container.querySelector('[role="banner"]')).toBeFalsy();+ });+});diff --git a/src/sse/handlers/chat.ts b/src/sse/handlers/chat.tsindex 9a9bb63a90..03d257337c 100644--- a/src/sse/handlers/chat.ts+++ b/src/sse/handlers/chat.ts@@ -661,7 +661,7 @@ async function handleSingleModelChat(});}- const { provider, model, sourceFormat, targetFormat, extendedContext } = resolved;+ const { provider, model, sourceFormat, targetFormat, extendedContext, apiFormat } = resolved;const forceLiveComboTest = runtimeOptions.forceLiveComboTest === true;const hasForcedConnection =typeof runtimeOptions.forcedConnectionId === "string" &&@@ -901,6 +901,7 @@ async function handleSingleModelChat(comboStepId: runtimeOptions.comboStepId ?? null,comboExecutionKey: runtimeOptions.comboExecutionKey ?? runtimeOptions.comboStepId ?? null,extendedContext,+ modelApiFormat: apiFormat,providerProfile,cachedSettings: runtimeOptions.cachedSettings,});