docs: Powering Reversa with OmniRoute — 50+ free LLM providers, 15–95% token compression

[diegosouzapw]

🎯 TL;DR

Adiciona uma seção opcional ao Reversa documentando como apontar Claude Code, Codex, Gemini CLI, Cursor e demais engines para uma instância local do OmniRoute — um gateway de IA open-source com ⭐ 5.3k+ stars no GitHub.

Resultado prático pro usuário do Reversa:

Antes	Com OmniRoute na frente
Cada CLI configurada separadamente, cada uma com sua chave	1 cofre unificado de chaves no dashboard
Cada chamada paga ao provedor da CLI	50+ provedores grátis disponíveis (11 free forever) — Kiro Opus 4.6, Qoder Kimi K2 ilimitado, Pollinations GPT-5 sem chave…
Prompts enviados na íntegra	Compressão RTK + Caveman 15–95% (~89% médio em sessões de Coding)
Um rate-limit derruba a sessão	Resiliência em 3 camadas + 14 estratégias de combo

Zero código executável adicionado. Zero dependência nova. Reversa segue sem chamar nenhum SDK de LLM.

---

🔍 Por que essa integração existe

O Reversa delega 100% da inteligência LLM para a CLI já instalada no ambiente do usuário (Claude Code, Codex, Cursor, Gemini CLI…). Isso é uma das suas garantias centrais: "does not request, store, or transmit API keys".

A consequência prática é que o custo de rodar /reversa num legado grande é o custo dessas CLIs. Num projeto de 500 módulos, o Archaeologist sozinho pode estourar quota mensal de uma conta Claude / OpenAI.

A solução natural — e que não viola nenhuma garantia do Reversa — é apontar a CLI para um proxy local que (a) tem dezenas de provedores grátis embutidos e (b) comprime os prompts antes de enviar. É exatamente o que o OmniRoute faz.

O Reversa em si não muda em nada. Apenas a CLI já instalada passa a falar com localhost:20128 em vez de api.anthropic.com / api.openai.com.

---

📦 O que muda

Arquivo	Tipo	Conteúdo
README.md	edit	Nova seção "⚡ Powering Reversa with OmniRoute (optional)" logo após Supported engines
docs/integrations/omniroute.md	novo	Walkthrough completo (EN) — setup, tuning por fase Reversa, FAQ
docs/integrations/omniroute.pt.md	novo	Tradução pt-BR
docs/integrations/omniroute.es.md	novo	Tradução espanhol
mkdocs.yml	edit	Entrada Integrations → OmniRoute no nav + traduções PT/ES via plugin i18n

Diff total: 5 arquivos · só markdown e YAML.

---

🆓 As features que justificam a integração

1. 50+ provedores grátis (11 free forever)

Lista parcial que aparece na seção:

Modelo	Grátis via	Limite
Claude Opus 4.6	Kiro	50 créditos/mês
Claude Sonnet 4.5 / Haiku 4.5	Kiro	50 créditos/mês
Kimi K2 Thinking	Qoder AI	♾️ Ilimitado
DeepSeek R1, Qwen3-Coder-Plus	Qoder AI	♾️ Ilimitado
GPT-5	Pollinations	🔓 Sem API key
LongCat Flash-Lite	LongCat	🔥 50M tokens/dia
Gemini 3 Flash	Gemini CLI	180K/mês

+ Cloudflare Workers AI, AgentRouter (US$100 crédito), Z.ai, Together, Groq, SambaNova, Cerebras, Mistral La Plateforme e outros.

2. Compressão de contexto RTK + Caveman (15–95%)

Tabela de impacto medido por fase Reversa que aparece no doc:

Fase	Compressão média
Scout	20–30%
Archaeologist	80–95%
Detective + Architect	50–70%
Writer + Reviewer	40–60%
Coding (Reversa Forward)	~89% média

Duas consequências para o Reversa: (a) legados grandes cabem nas quotas free; (b) janela de contexto efetiva fica muito maior — o Architect enxerga mais arquivos por chamada.

3. Combos, resiliência e cofre de chaves

• 14 estratégias de combo (priority, weighted, P2C, least-used, cost-optimized, context-relay, auto-combo…)
• Resiliência 3 camadas: provider circuit breaker → connection cooldown → per-model lockout
• Cofre unificado de chaves com dashboard de custo/quota em tempo real
• Tradução automática OpenAI ↔ Claude ↔ Gemini ↔ Responses API
• MCP server (37 tools), A2A, memória vetorial, guardrails, evals

---

🛡️ Garantias do Reversa preservadas

Esse é o ponto delicado dado o aviso oficial do Reversa. A integração foi desenhada para não violar nenhuma promessa:

Garantia oficial do Reversa	Como continua valendo
"does not request, store, or transmit API keys"	Reversa continua sem código que toque em chaves. Quem fala com OmniRoute é a CLI já instalada do usuário, igual hoje fala com api.anthropic.com
"never deletes or modifies existing files"	PR só adiciona arquivos novos + edita 2 (README.md, mkdocs.yml) — comportamento dos agentes intocado
"all writes restricted to .reversa/ and _reversa_sdd/"	Nada muda. O OmniRoute escreve no diretório dele (~/.omniroute/)
Zero dependência de LLM externa	Nenhuma nova dep no package.json, nenhuma chamada de rede a partir do código Reversa
Local-first	OmniRoute roda em localhost:20128. Seu legado nunca sai da máquina, exceto pela chamada LLM em si (igual hoje)

Cada um desses pontos está reafirmado dentro do doc, na seção de FAQ.

---

🌍 Tradução nos 3 idiomas do projeto

O Reversa mantém docs em EN/PT/ES via plugin i18n (sufixo .pt.md / .es.md). Esse PR entrega os 3 simultaneamente, com nav_translations para Integrations → Integrações → Integraciones.

---

🧪 Como validar localmente

gh pr checkout <este-pr>
pip install mkdocs-material mkdocs-static-i18n
mkdocs serve
# abrir http://127.0.0.1:8000/integrations/omniroute/
# trocar idioma no header e validar EN/PT/ES

---

✅ Checklist

• Sem deps novas (package.json intocado)
• Sem mudanças em código executável (bin/, lib/, agents/, templates/ intocados)
• Mudanças confinadas a README.md, mkdocs.yml e arquivos novos em docs/integrations/
• Tradução nos 3 idiomas oficiais (EN/PT/ES)
• Aviso explícito de que a integração é opcional e local-first
• FAQ reafirmando as 5 garantias oficiais do Reversa
• Tabela de tuning por fase Reversa (Scout, Archaeologist, Detective, Architect, Writer, Coding, Pricing)
• Sem links de comunidade/marketing externos no corpo da doc (foco técnico)

---

💬 Notas para o @sandeco

• A doc deixa explícito em 3 lugares (README, intro do guia e FAQ) que o OmniRoute é opcional, local-first e que o Reversa em si não chama o proxy. Quero garantir que o framing respeita a posição do projeto sobre não ter dependências de LLM.
• Sou autor do OmniRoute (diegosouzapw). Disclosure feito aqui pra transparência. Aberto a ajustar qualquer tom comercial que pareça forte demais — minha intenção é só documentar um padrão de integração que entrega valor real pro usuário do Reversa rodando em legados grandes.
• Se preferir mover a seção do README para um lugar diferente, encurtar a tabela de provedores grátis, ou remover qualquer parte específica, é só apontar que ajusto na hora.

Obrigado pelo trabalho incrível com o Reversa 🙏

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3f8b85779d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Use Gemini CLI's actual base URL variable

This setup won't route Gemini CLI through OmniRoute: the official Gemini CLI configuration documents GOOGLE_GEMINI_BASE_URL as the Gemini API base URL override and GEMINI_API_KEY as the API-key variable, but not GEMINI_API_BASE. Users following this row (also repeated in the README and translations) will keep sending Gemini CLI traffic to Google's default endpoint instead of localhost, so the documented integration silently fails for that engine.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Don't claim pricing reads OmniRoute usage

This describes a capability the Reversa pricing agent does not have: agents/reversa-pricing-estimate/SKILL.md explicitly says not to consult network, WebSearch, or external services, and its prerequisites only read local profile.json and size.json. Users who enable OmniRoute cost tracking based on this row will expect /reversa-pricing-estimate to consume GET /api/usage/summary, but that code path cannot run and it contradicts the page's guarantee that Reversa does not call OmniRoute.

Useful? React with 👍 / 👎.