<div align="center">

# 🚀 OmniRoute — The Free AI Gateway

### Never stop coding. Save 15-75% tokens with prompt 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 (29 tools)**, **A2A Protocol**, and **Memory/Skills** systems. Available in **40+ languages**._

**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**

<br/>

<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>

<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>

<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-75-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>

---

<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 -->

[![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)

</div>

---

## 🖼️ Main Dashboard

<div align="center">
  <img src="./docs/screenshots/MainOmniRoute.png" alt="OmniRoute Dashboard" width="800"/>
</div>

---

## 📸 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>

---

### 🤖 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.png" 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.png" 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.png" 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.png" 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>

---

## 📺 OmniRoute in Action — Video Guides

<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-75% tokens per request
✅ **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

---

## 📧 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?

When opening an issue, please run the system-info command and attach the generated file:

```bash
npm run system-info
```

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.

---

## 🛠️ 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>

---

## 🔄 How It Works

```
┌─────────────┐
│  Your CLI   │  (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
│   Tool      │
└──────┬──────┘
       │ http://localhost:20128/v1
       ↓
┌──────────────────────────────────────────────────┐
│              OmniRoute (Smart Router)             │
│  • 🗜️ Prompt Compression (save 15-75% tokens)    │
│  • 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-75% token savings
```

---

## 🗜️ Prompt Compression — Save 15-75% Tokens Automatically

> **Why use many token when few token do trick?** OmniRoute's built-in compression pipeline reduces token usage on every request — before it even reaches the provider. Inspired by [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 (5 modes)          │     │  receives    │
│   (10,000 tok)   │     │                              │     │  compressed  │
│                  │     │  🪶 Lite ........... ~15%     │     │  (2,500 tok) │
│                  │     │  🪨 Standard ....... ~30%     │     │              │
│                  │     │  ⚡ Aggressive ..... ~50%     │     │  💰 75% saved │
│                  │     │  🔥 Ultra .......... ~75%     │     │              │
└──────────────────┘     └─────────────────────────────┘     └──────────────┘
```

### 5 Compression Modes

| 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 |

### 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."

**🪨 After compression (19 tokens):**

> "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
  ├─ 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 → Settings → Compression → Pick your mode
```

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.

> 🪨 **Fun fact:** The standard/caveman mode is inspired by [Caveman](https://github.com/JuliusBrussee/caveman) — the viral project that proved "caveman speak" cuts 65% of tokens while keeping 100% technical accuracy. OmniRoute takes this further with a **5-mode pipeline** that goes from gentle whitespace cleanup all the way to aggressive heuristic pruning.

📖 **Full compression documentation:** [`docs/COMPRESSION_GUIDE.md`](docs/COMPRESSION_GUIDE.md)

---

## 🎯 What OmniRoute Solves

> **Every developer using AI tools faces these problems daily.** OmniRoute solves them all.

| #   | 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     |

<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)

---

## 🆓 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.

> **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).

## ⚡ Quick Start

### 1) Install and run

```bash
npm install -g omniroute
omniroute
```

Dashboard opens at `http://localhost:20128` · API at `http://localhost:20128/v1`.

### 2) Connect providers

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)

### 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)
```

Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and any OpenAI-compatible tool.

<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 --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>

---

## 🐳 Docker

OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).

**Quick run:**

```bash
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
```

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 Docker documentation:** [`docs/DOCKER_GUIDE.md`](docs/DOCKER_GUIDE.md) — Compose profiles, Caddy HTTPS, Cloudflare tunnels, and more.

---

## 📱 Multi-Platform — Run Anywhere

> OmniRoute runs on **Web**, **Desktop (Electron)**, **Android (Termux)**, and as a **Progressive Web App (PWA)**.

| 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>

- 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)

</details>

<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 — 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

### 🆓 1proxy — Free Proxy Marketplace

> Contributed by [@oyi77](https://github.com/oyi77) — [#1847](https://github.com/diegosouzapw/OmniRoute/pull/1847)

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)

---

---

## 💰 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.

---

## 🆓 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>

📖 **Complete free provider directory:** [`docs/FREE_TIERS.md`](docs/FREE_TIERS.md) — 25+ providers, quotas, base URLs, model tables, and OmniRoute combo setup.

---

## 🎙️ Free Transcription Combo

> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.

| 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)        |

---

**Suggested combo in `/dashboard/combos`:**

```
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
```

Then in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.

## 💡 Key Features

> **4,690+ automated tests** across 517 test files. Not just a relay — a full operational platform.

| 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** — 5-mode pipeline (off → lite → standard → aggressive → ultra)             | Save 15-75% tokens automatically |
| 🤖 **MCP Server** — 29 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    |

<details>
<summary><b>📋 Complete feature list — 30+ capabilities</b></summary>

**Routing & Intelligence**

- 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

**Translation & Compatibility**

- 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

**Protocols**

- A2A Server — JSON-RPC 2.0, SSE streaming, task lifecycle, skills
- ACP — CLI agent discovery (14 agents + custom)

**Platform**

- Desktop (Electron) · Android (Termux) · PWA · Docker (AMD64 + ARM64)
- Cloudflare / Tailscale / ngrok tunnels · 40+ languages with RTL
- Semantic + signature cache (two-tier) · Request idempotency + deduplication

**Observability**

- Health dashboard — uptime, breakers, cache, lockouts
- Evaluation framework — golden set testing · Webhooks · Compliance audit

**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:**

```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
```

📖 [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)

</details>

---

## 🎯 Use Cases — Ready-Made Combo Playbooks

### Case 1: "I have a Claude Pro subscription"

**Problem:** Quota expires unused, rate limits during heavy coding sessions.

```
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
```

### 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
```

### Case 3: "I need 24/7 coding, no interruptions"

**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` |

---

## 📖 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                                    |

### Protocols (MCP + A2A)

```bash
# MCP (stdio transport)
omniroute --mcp

# A2A (JSON-RPC 2.0)
curl http://localhost:20128/.well-known/agent.json
```

### 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) — 29 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>

---

## ❓ 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

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>

---

## 🐛 Troubleshooting

| 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                 |

📖 **Full troubleshooting guide:** [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.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>

---

## 📖 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)           | 5-mode pipeline: off / lite / standard / aggressive / ultra            |
| [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    |

---

## ⭐ 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.

---

## 👥 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

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

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
```

---

## 📊 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.

Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.

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.

---

## 📄 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 -->
