diff --git a/README.md b/README.md index 940326ea2f..cc49454f00 100644 --- a/README.md +++ b/README.md @@ -960,57 +960,72 @@ same process on one port, so there is no separate CLI-only package today. ### 📘 Getting Started -- **[User Guide](docs/guides/USER_GUIDE.md)** — Providers, combos, CLI integration, deployment -- **[Setup Guide](docs/guides/SETUP_GUIDE.md)** — Full install methods, CLI tool configs, protocol setup, timeout tuning -- **[CLI Tools Guide](docs/reference/CLI-TOOLS.md)** — Per-tool setup for Claude Code, Codex, Cursor, Cline, OpenClaw, Kilo, Copilot -- **[Remote Mode](docs/guides/REMOTE-MODE.md)** — Drive a remote OmniRoute (VPS) from your laptop CLI via scoped access tokens -- **[Claude Code Config](docs/guides/CLAUDE-CODE-CONFIGURATION.md)** — Point Claude Code at OmniRoute (local/remote) with `launch` + per-model profiles -- **[Quick Start](README.md#-quick-start)** — 3-step install → connect → configure + + + + + + + + +
DocumentDescription
User GuideProviders, combos, CLI integration, deployment
Setup GuideFull install methods, CLI tool configs, protocol setup, timeout tuning
CLI Tools GuidePer-tool setup for Claude Code, Codex, Cursor, Cline, OpenClaw, Kilo, Copilot
Remote ModeDrive a remote OmniRoute (VPS) from your laptop CLI via scoped access tokens
Claude Code ConfigPoint Claude Code at OmniRoute (local/remote) with launch + per-model profiles
Quick Start3-step install → connect → configure
### 🔧 Operations & Deployment -- **[Docker Guide](docs/guides/DOCKER_GUIDE.md)** — Docker run, Compose profiles, Caddy HTTPS, tunnels, image tags -- **[Podman Guide](contrib/podman/README.md)** — Quadlet systemd integration, podman-compose, SELinux -- **[VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md)** — Complete guide: VM + nginx + Cloudflare setup -- **[Fly.io Deployment](docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md)** — Deploy to Fly.io with persistent storage -- **[Termux Guide](docs/guides/TERMUX_GUIDE.md)** — Run OmniRoute on Android via Termux -- **[PWA Guide](docs/guides/PWA_GUIDE.md)** — Progressive Web App install, caching, architecture -- **[Uninstall Guide](docs/guides/UNINSTALL.md)** — Clean removal for all install methods -- **[Environment Config](docs/reference/ENVIRONMENT.md)** — Complete `.env` variables and references + + + + + + + + + + +
DocumentDescription
Docker GuideDocker run, Compose profiles, Caddy HTTPS, tunnels, image tags
Podman GuideQuadlet systemd integration, podman-compose, SELinux
VM DeploymentComplete guide: VM + nginx + Cloudflare setup
Fly.io DeploymentDeploy to Fly.io with persistent storage
Termux GuideRun OmniRoute on Android via Termux
PWA GuideProgressive Web App install, caching, architecture
Uninstall GuideClean removal for all install methods
Environment ConfigComplete .env variables and references
### 🧠 Features & Architecture -- **[Architecture](docs/architecture/ARCHITECTURE.md)** — System architecture, data flow, and internals -- **[Compression Guide](docs/compression/COMPRESSION_GUIDE.md)** — 7-option pipeline: off / lite / standard / aggressive / ultra / RTK / stacked -- **[RTK Compression](docs/compression/RTK_COMPRESSION.md)** — Command-output compression, filters, trust, verify, raw-output recovery -- **[Compression Engines](docs/compression/COMPRESSION_ENGINES.md)** — Caveman, RTK, stacked pipelines, dashboard/API/MCP surfaces -- **[Compression Rules Format](docs/compression/COMPRESSION_RULES_FORMAT.md)** — JSON rule-pack schemas for Caveman and RTK filters -- **[Compression Language Packs](docs/compression/COMPRESSION_LANGUAGE_PACKS.md)** — Language detection and Caveman rule-pack authoring -- **[Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md)** — Circuit breakers, cooldowns, queue, anti-thundering herd, TLS spoofing -- **[Auto-Combo Engine](docs/routing/AUTO-COMBO.md)** — 12-factor scoring, mode packs, self-healing -- **[Proxy Guide](docs/ops/PROXY_GUIDE.md)** — 3-level proxy system, 1proxy marketplace, registry CRUD -- **[Free Tiers](docs/reference/FREE_TIERS.md)** — 25+ free API providers consolidated directory -- **[Features Gallery](docs/guides/FEATURES.md)** — Visual dashboard tour with screenshots -- **[Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md)** — Beginner-friendly codebase walkthrough + + + + + + + + + + + + + + +
DocumentDescription
ArchitectureSystem architecture, data flow, and internals
Compression Guide7-option pipeline: off / lite / standard / aggressive / ultra / RTK / stacked
RTK CompressionCommand-output compression, filters, trust, verify, raw-output recovery
Compression EnginesCaveman, RTK, stacked pipelines, dashboard/API/MCP surfaces
Compression Rules FormatJSON rule-pack schemas for Caveman and RTK filters
Compression Language PacksLanguage detection and Caveman rule-pack authoring
Resilience GuideCircuit breakers, cooldowns, queue, anti-thundering herd, TLS spoofing
Auto-Combo Engine12-factor scoring, mode packs, self-healing
Proxy Guide3-level proxy system, 1proxy marketplace, registry CRUD
Free Tiers25+ free API providers consolidated directory
Features GalleryVisual dashboard tour with screenshots
Codebase DocumentationBeginner-friendly codebase walkthrough
### 🤖 Protocols & APIs -- **[API Reference](docs/reference/API_REFERENCE.md)** — All endpoints with examples -- **[OpenAPI Spec](docs/openapi.yaml)** — OpenAPI 3.0 specification -- **[MCP Server](open-sse/mcp-server/README.md)** — 104 MCP tools, IDE configs, Python/TS/Go clients -- **[MCP Server Guide](docs/frameworks/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/frameworks/A2A-SERVER.md)** — A2A agent card, tasks, skills, and streaming + + + + + + + + +
DocumentDescription
API ReferenceAll endpoints with examples
OpenAPI SpecOpenAPI 3.0 specification
MCP Server104 MCP tools, IDE configs, Python/TS/Go clients
MCP Server GuideMCP installation, transports, and tool reference
A2A ServerJSON-RPC 2.0 protocol, skills, streaming, task mgmt
A2A Server GuideA2A agent card, tasks, skills, and streaming
### 📋 Project & Quality -- **[Contributing](CONTRIBUTING.md)** — Development setup and guidelines -- **[Branching & Release Model](docs/ops/BRANCHING_MODEL.md)** — Where PRs target (`release/*`), what `main` and tags mean -- **[Changelog](CHANGELOG.md)** — Full per-version release history -- **[Security Policy](SECURITY.md)** — Vulnerability reporting and security practices -- **[i18n Guide](docs/guides/I18N.md)** — 40+ language support, translation workflow, RTL -- **[Release Checklist](docs/ops/RELEASE_CHECKLIST.md)** — Pre-release validation steps -- **[Coverage Plan](docs/ops/COVERAGE_PLAN.md)** — Test coverage strategy and 25,000+ test suite + + + + + + + + + +
DocumentDescription
ContributingDevelopment setup and guidelines
Branching & Release ModelWhere PRs target (release/*), what main and tags mean
ChangelogFull per-version release history
Security PolicyVulnerability reporting and security practices
i18n Guide40+ language support, translation workflow, RTL
Release ChecklistPre-release validation steps
Coverage PlanTest coverage strategy and 25,000+ test suite

@@ -1217,78 +1232,85 @@ OmniRoute stands on the shoulders of giants. It started as a fork of **[9router] ### 🧬 Lineage & gateway -| Project | ⭐ | -| :-------------------------------------------------------------- | :---: | -| **[9router](https://github.com/decolua/9router)** | 22.7k | -| **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** | 43.6k | -| **[LiteLLM](https://github.com/BerriAI/litellm)** | 54.0k | + + + + + +
Project⭐How it inspired OmniRoute
9router22.7kThe original project this fork is built on — extended here with multi-modal APIs and a full TypeScript rewrite.
CLIProxyAPI43.6kThe Go implementation that inspired this JavaScript / TypeScript port.
LiteLLM54.0kThe AI gateway whose public pricing dataset feeds our cost-tracking sync and whose provider-normalization model informed our routing.
### 🗜️ Context & token compression — engines -| Project | ⭐ | -| :------------------------------------------------------------ | :---: | -| **[Caveman](https://github.com/JuliusBrussee/caveman)** | 90.8k | -| **[RTK – Rust Token Killer](https://github.com/rtk-ai/rtk)** | 71.8k | -| **[headroom](https://github.com/headroomlabs-ai/headroom)** | 60.1k | -| **[LLMLingua](https://github.com/microsoft/LLMLingua)** | 6.5k | -| **[llmlingua-2-js](https://github.com/atjsh/llmlingua-2-js)** | 30 | -| **[Troglodita](https://github.com/leninejunior/troglodita)** | 26 | -| **[ponytail](https://github.com/DietrichGebert/ponytail)** | 86.0k | + + + + + + + + + +
Project⭐How it inspired OmniRoute
Caveman90.8kThe viral "why use many token when few token do trick" project — its caveman-speak philosophy powers our standard compression mode and 30+ filler/condensation rules.
RTK – Rust Token Killer71.8kHigh-performance command-output compression — inspired our RTK engine, JSON filter DSL, raw-output recovery and the stacked RTK → Caveman pipeline.
headroom60.1kReversible context-compression (SmartCrusher) — inspired our headroom engine and the ccr retrieve-marker pattern.
LLMLingua6.5kPrompt-compression research (LLMLingua / LLMLingua-2) — inspired our async, code-safe, fail-open llmlingua engine.
llmlingua-2-js30The JS/ONNX port (MobileBERT / XLM-RoBERTa) used as the worker-thread backend for our LLMLingua engine.
Troglodita26PT-BR token compression — powers our pt-BR language pack: pleonasm reduction and filler removal tuned for Brazilian-Portuguese grammar.
ponytail86.0kThe viral "lazy senior dev" YAGNI-coder skill — inspired our less-code Output Style: smallest-working-change steering that cuts _generated_ code (the output-axis sibling to Caveman's terse prose).
### 🧩 Compact formats, token research & code-aware tooling -| Project | ⭐ | -| :------------------------------------------------------------------------- | :---: | -| **[TOON](https://github.com/toon-format/toon)** | 24.9k | -| **[GCF – Graph Compact Format](https://github.com/blackwell-systems/gcf)** | 22 | -| **[token-optimizer-mcp](https://github.com/ooples/token-optimizer-mcp)** | 444 | -| **[token-savior](https://github.com/Mibayy/token-savior)** | 1.1k | -| **[token-saver](https://github.com/ppgranger/token-saver)** | 117 | -| **[token-optimizer](https://github.com/alexgreensh/token-optimizer)** | 1.7k | -| **[TokenMizer](https://github.com/Shweta-Mishra-ai/tokenmizer)** | 16 | -| **[OmniCompress](https://github.com/jessefreitas/OmniCompress)** | 3 | -| **[mcp-compressor](https://github.com/atlassian-labs/mcp-compressor)** | 98 | -| **[RepoMapper](https://github.com/pdavis68/RepoMapper)** | 187 | -| **[quiet-shell-mcp](https://github.com/mrsimpson/quiet-shell-mcp)** | 4 | -| **[ts-morph](https://github.com/dsherret/ts-morph)** | 6.1k | + + + + + + + + + + + + + + +
Project⭐How it inspired OmniRoute
TOON24.9kToken-Oriented Object Notation — its columnar, header-plus-rows model shaped our tabular compaction stage.
GCF – Graph Compact Format22First inspired our tabular compaction stage; now its zero-dependency, lossless generic-profile encoder is vendored directly as the Headroom codec (MIT, SPDX-marked), current with GCF spec v3.2.
token-optimizer-mcp444Brotli/SQLite cache + per-session context-delta — inspired our session-dedup engine.
token-savior1.1kBash-output compaction + MCP profiles — inspired our compression bail-out discipline and MCP tool-manifest reduction.
token-saver117Content-aware, per-file-type output compression with failure-aware bail-out — validated our per-type dispatch and minimum-gain skip.
token-optimizer1.7k"Find the ghost tokens" — its offload + recoverable-handle pattern informed our CCR offload thinking.
TokenMizer16A session-graph + cross-turn line-dedup blueprint that informed our session-dedup design.
OmniCompress3Rust columnar-JSON + content-addressed retrieve + cross-message dedup — validated our headroom/ccr/session-dedup engine design and the cache-stable "compressed form is position-independent" invariant.
mcp-compressor98MCP tool-schema/description compression — informed our MCP tool-manifest cardinality reduction.
RepoMapper187Aider-style repo-map ranking — informed our repo-map / retrieval-ranking exploration.
quiet-shell-mcp4Declarative shell-output reduction over MCP — validated our declarative bash-output compaction.
ts-morph6.1kTypeScript Compiler API toolkit — inspired our parser-based comment removal that preserves string, template and regex literals.
### 🧠 Memory & RAG -| Project | ⭐ | -| :------------------------------------------------------ | :---: | -| **[Mem0](https://github.com/mem0ai/mem0)** | 61.2k | -| **[Letta (MemGPT)](https://github.com/letta-ai/letta)** | 23.9k | -| **[WFGY](https://github.com/onestardao/WFGY)** | 1.8k | + + + + + +
Project⭐How it inspired OmniRoute
Mem061.2kUniversal memory layer — its proxy-as-write/read-boundary model shaped our memory architecture.
Letta (MemGPT)23.9kStateful agents with tiered memory — inspired our Context Control & Recovery (CCR) tiered model.
WFGY1.8kThe ProblemMap taxonomy of 16 recurring RAG/LLM failure modes — the shared vocabulary in our troubleshooting guide.
### 🛰️ Traffic inspection, MITM & transparent proxy -| Project | ⭐ | -| :--------------------------------------------------------------- | :--: | -| **[llm-interceptor](https://github.com/chouzz/llm-interceptor)** | 49 | -| **[ProxyBridge](https://github.com/InterceptSuite/ProxyBridge)** | 5.5k | + + + + +
Project⭐How it inspired OmniRoute
llm-interceptor49MITM interception/analysis of coding-assistant ↔ LLM traffic — our Traffic Inspector ports its SSE merge, conversation normalization, host passthrough and secret masking (MIT).
ProxyBridge5.5kTransparent per-process proxy routing — inspired our crash-safe MITM teardown, socket idle-timeouts, /proc process attribution and TPROXY capture.
### 📚 Model data, observability & UI -| Project | ⭐ | -| :---------------------------------------------------------- | :---: | -| **[models.dev](https://github.com/anomalyco/models.dev)** | 6.0k | -| **[React Flow / xyflow](https://github.com/xyflow/xyflow)** | 37.7k | -| **[LangGraph](https://github.com/langchain-ai/langgraph)** | 37.6k | -| **[Langfuse](https://github.com/langfuse/langfuse)** | 31.4k | -| **[Kiali](https://github.com/kiali/kiali)** | 3.6k | -| **[lobe-icons](https://github.com/lobehub/lobe-icons)** | 2.2k | + + + + + + + + +
Project⭐How it inspired OmniRoute
models.dev6.0kOpen database of AI model specs, pricing and capabilities — synced natively into our model catalog.
React Flow / xyflow37.7kThe node-based graph library powering our real-time Compression Studio and Combo/Routing Studio.
LangGraph37.6kLangGraph Studio's live workflow-graph visualization inspired our Studios' real-time cascade view.
Langfuse31.4kIts trace → span → generation observability model shaped our Compression Studio waterfall.
Kiali3.6kIstio service-mesh observability — inspired our circuit-breaker badges and error-edge visuals in the Routing/Combo Studio.
lobe-icons2.2kAI/LLM brand logos that render the provider icons across our dashboard.
### 🛡️ Security -| Project | ⭐ | -| :-------------------------------------------------------------------------------- | :-: | -| **[awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)** | 710 | + + + +
Project⭐How it inspired OmniRoute
awesome-secure-defaults710A curated list of secure-by-default libraries that guides our security choices (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink).
### 🧭 Complementary tools -| Project | ⭐ | -| :------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | -| **[CodeWebChat](https://github.com/robertpiosik/CodeWebChat)** | Editor-side companion — VS Code + browser extension that autofills 15+ chatbot web UIs with editor context. Owns the free-web-UI rail alongside OmniRoute's API rail; can point its API mode at OmniRoute. | + + +
Project⭐How it inspired OmniRoute
## 📄 License