Skip to content

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

feat: CLI Integration Suite for issue #2016

oyi772d601ea4592b
diff --git a/@omniroute/opencode-provider/README.md b/@omniroute/opencode-provider/README.md
new file mode 100644
index 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.ts
new file mode 100644
index 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.js
new file mode 100644
index 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.ts
new file mode 100644
index 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.json
new file mode 100644
index 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.md
index 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/>
-[![npm](https://img.shields.io/npm/v/omniroute?logo=npm&style=flat-square)](https://www.npmjs.com/package/omniroute)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
-[![Node](https://img.shields.io/badge/node-%E2%89%A520.20.2-brightgreen?style=flat-square)](package.json)
-[![Stars](https://img.shields.io/github/stars/diegosouzapw/OmniRoute?style=social)](https://github.com/diegosouzapw/OmniRoute)
-[![Trendshift](https://trendshift.io/api/badge/repositories/23589)](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">
+
+[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute)
+![NPM Weekly](https://img.shields.io/npm/dw/omniroute?label=npm/week&color=cb3837&logo=npm)
+![NPM Monthly](https://img.shields.io/npm/dm/omniroute?label=npm/month&color=cb3837&logo=npm)
+![NPM Yearly](https://img.shields.io/npm/d18m/omniroute?label=npm/year&color=cb3837&logo=npm)
+
+[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute)
+![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute?label=docker%20pulls&logo=docker&color=2496ED)
+![Electron Downloads](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=electron%20downloads&logo=electron&color=47848F)
+[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](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 |
+[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)
+[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw)
+[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)
+[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-📺 **Watch in action:** [Video demo](https://www.youtube.com/@diegosouza-pw)
+</div>
---
-## 🖼️ Dashboard Preview
+## 🖼️ Main Dashboard
-![OmniRoute Main Dashboard](docs/screenshots/MainOmniRoute.png)
+<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>
+---
-| | |
-| --------------------------------------------- | ---------------------------------------------------- |
-| ![Providers](docs/screenshots/Provedores.png) | ![Combos](docs/screenshots/Combos.png) |
-| ![Routing](docs/screenshots/Roteamento.png) | ![Compression](docs/screenshots/Compress%C3%A3o.png) |
-| ![Audit](docs/screenshots/Auditoria.png) | ![Analytics](docs/screenshots/Analytics.png) |
+## 📸 Dashboard Preview
+
+<details>
+<summary><b>Click to see dashboard screenshots</b></summary>
+
+| Page | Screenshot |
+| -------------- | ------------------------------------------------- |
+| **Providers** | ![Providers](docs/screenshots/01-providers.png) |
+| **Combos** | ![Combos](docs/screenshots/02-combos.png) |
+| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) |
+| **Health** | ![Health](docs/screenshots/04-health.png) |
+| **Translator** | ![Translator](docs/screenshots/05-translator.png) |
+| **Settings** | ![Settings](docs/screenshots/06-settings.png) |
+| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) |
+| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) |
+| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |
</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
+
+[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](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.mjs
new file mode 100644
index 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.mjs
index 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 override
Checks:
- 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
index 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.mjs
index 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 openai
omniroute providers available --category api-key
omniroute 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[0m
Dashboard: http://localhost:<dashboard-port>
API: http://localhost:<api-port>/v1
diff --git a/docs/AUTO-COMBO.md b/docs/AUTO-COMBO.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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.json
index 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.tsx
index 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}
+<<<<<<< HEAD
aria-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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
index 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,
});