LLM Router

llm-router

Pare de gastar sua cota do Claude Pro/Max com perguntas que um modelo gratuito pode responder.

O llm-router se conecta ao ciclo de vida da sua ferramenta de codificação, lê cada prompt antes do modelo, e elabora uma resposta em um modelo gratuito ou local primeiro. Não são necessárias chaves de API em uma assinatura do Claude — o roteamento passa por ferramentas MCP e modelos locais.

_{Uma ressalva: as respostas roteadas são consultivas por padrão — o Claude ainda assume a vez, a menos que LLM_ROUTER_ZERO_CLAUDE=1. Por padrão, algumas chamadas de ferramenta aguardam até que um prompt seja roteado; LLM_ROUTER_ENFORCE=off desativa isso. Os números de taxa de rascunho e aceitação estão em docs/MEASUREMENT.md, com seus n, janela e condições.}

📑 Índice

• Por que instalar isso
• Início Rápido
• Funciona Com
• Como Funciona
• Recursos
• Referência
• Economia
• Confiança e Segurança
• Documentação
• Empresarial, Contribuição, Licença

---

Por que instalar isso

Você está em um plano Claude Pro ou Max, não gastou um centavo além dele, e ainda assim atingiu o limite de cinco horas — não porque pediu demais, mas porque todos os prompts foram para o modelo premium: "o que significa este erro", "reformate este JSON", "o serviço está no ar" consumiram a mesma cota que a pergunta que realmente precisava dela.

Por que um proxy não consegue fazer isso

A maioria dos roteadores aqui é um proxy: seu agente encaminha solicitações usando suas chaves de API. Isso tem um limite rígido — um proxy não pode interceptar uma sessão autenticada por uma assinatura, porque não há chave para encaminhar.

	Paga por token	Paga uma assinatura
O que acaba	sua fatura	sua janela de cinco horas
Precisa de chaves de API	sim	não
Um proxy pode ajudar	sim	não — nada para interceptar
llm-router ajuda	sim	sim

Honestidade como recurso

llm-router status relata economias verificadas e não verificadas separadamente, cada uma com seu próprio n — não uma porcentagem combinada. Este projeto não publica uma porcentagem geral de economia; qualquer número depende da sua própria carga de trabalho. Veja Economia abaixo.

---

Início Rápido

pip install llm-routing        # installs the `llm-router` command
llm-router install             # wire up Claude Code (default host)
llm-router doctor               # check provider connectivity and setup
llm-router status               # verify it's routing — est. savings vs baseline

Funciona sem chaves de API em uma assinatura Claude Pro/Max — o roteamento passa por ferramentas MCP e modelos locais. Adicionar chaves de provedores amplia o pool; nada exige isso. Veja guide/PROVIDERS.md. Para instalar em outro host, veja Funciona Com.

Agentes Python roteiam em processo, sem servidor: from llm_router import Router; r = Router(budget_usd=0.50).run("...") (await .arun(...) em código assíncrono; BudgetExceeded quando o limite é atingido).

---

Funciona Com

Host	Instalação
Claude Code (padrão)	llm-router install
Codex CLI	llm-router install --host codex
OpenCode	llm-router install --host opencode
Gemini CLI	llm-router install --host gemini-cli
GitHub Copilot CLI	llm-router install --host copilot-cli
OpenClaw	llm-router install --host openclaw
Trae IDE	llm-router install --host trae
Pi (pi.dev)	planejado (v16 P2.12); --host pi informa o motivo e sai com código 2
Factory Droid	llm-router install --host factory
Claude Desktop	llm-router install --host desktop
VS Code (MCP nativo)	llm-router install --host vscode
Cursor	llm-router install --host cursor
GitHub Copilot no VS Code (extensão de capacidade, sem roteamento de custo)	llm-router install --host copilot
Windsurf / Cascade	llm-router install --host windsurf
Kimi Code (Moonshot AI)	planejado (v16 P2.12); --host kimi informa o motivo e sai com código 2

llm-router install --host all instala ou imprime toda a configuração de cada host em uma única passada. Detalhes completos por host, incluindo o que cada host realmente não pode fazer: guide/HOST_SUPPORT_MATRIX.md.

---

Como Funciona

Os hooks interceptam o prompt antes que o modelo da sua ferramenta de codificação o veja. Uma heurística gratuita de regex o classifica instantaneamente, pontuando cerca de metade dos prompts reais com confiança — 788 de 1.571 medidos (scripts/measure_low_signal_rate.py, executado em 2026-09-23); o restante cai em um padrão. Um prompt roteável recebe um rascunho de um modelo gratuito/local primeiro, depois sobe na cadeia em direção a modelos pagos apenas se necessário.

O rascunho é consultivo — entregue ao Claude como uma dica não verificada, não uma substituição de turno, a menos que LLM_ROUTER_ZERO_CLAUDE=1 esteja definido. A aplicação atua no nível de chamada de ferramenta: smart (padrão) segura chamadas de ferramenta selecionadas até que o prompt seja roteado; off desativa isso. Modos completos e substituições por host: guide/GETTING_STARTED.md.

---

Recursos

• Segredos nunca saem da sua máquina. Um prompt contendo uma chave de API, token ou chave privada roteia apenas para modelos locais — falha fechada.
• Fallback automático com disjuntores. Um provedor que falha ou limita a taxa é ignorado, não repetido até o esgotamento.
• Você pode ver funcionando. Uma linha de status, título do terminal e notificação do sistema operacional mostram o último modelo roteado, economia e saúde.
• Resumo no final da sessão. Economia vs. linha de base, mistura de níveis, custo por provedor, latência p50/p95/p99 e principais rotas.
• Mídia e pipelines também. llm_image / llm_video / llm_audio, e llm_orchestrate para pesquisa em várias etapas.

---

Referência

A superfície MCP padrão mostra 12 ferramentas de porta de entrada; LLM_ROUTER_SLIM=off mostra tudo o que está registrado.

Tópico	O quê	Guia
CLI	install, status, gain, doctor, okf index/status, sessions status e mais	guide/GETTING_STARTED.md
Provedores	Gratuito primeiro — Ollama (local), OpenRouter, Gemini, Groq, sua assinatura do Claude	guide/PROVIDERS.md
Políticas de Roteamento	conservative → balanced (padrão) → cost_aggressive; limites e esquema YAML	guide/POLICIES.md
Ferramentas MCP	Cada ferramenta com sua assinatura	guide/TOOLS.md

llm-router gain today           # savings so far today
llm-router okf status           # knowledge base freshness
llm-router sessions status      # per-session summary

---

Economia

Os números de economia são um contrafactual — o que os mesmos tokens teriam custado no preço de tabela da API, contra o que foi realmente gasto — não dinheiro economizado em uma assinatura fixa. llm-router status e llm-router savings-report dividem economias verificadas de não verificadas, cada uma com seu próprio n. Metodologia, suposições e limitações: docs/MEASUREMENT.md.

---

Confiança e Segurança

O llm-router roda inteiramente na sua máquina — sem proxy hospedado, nada enviado a um serviço llm-router, sem conta necessária. Uma verificação de fundamentação (src/llm_router/grounding.py) descarta qualquer rascunho que cite um arquivo ou função ausente de seu contexto e do repositório indexado, caindo para o Claude.

LLM_ROUTER_DIRECT_EXECUTION está ativado por padrão — um modelo local recebe write_file, edit_file e run_command sob um caminho confinado e na lista de permissões, e nada disso impede exclusões direcionadas, git push --force ou exfiltração. Redirecionamentos de shell e cópias que gravam fora da raiz do projeto são recusados por um alarme estático, não por uma sandbox; uma sandbox do sistema operacional é 16.1. Um comando que o alarme não consegue julgar (um one-liner de interpretador, sudo, um $(...)) retorna needs_approval, mas a aprovação não está conectada a lugar nenhum ainda, então ambos os caminhos de comando o tratam como recusado e não o executam. Desative-o com LLM_ROUTER_DIRECT_EXECUTION=false. Análise completa: SECURITY.md.

Auto-auditorias são publicadas em audit/ e docs/repo_goals/AUDIT-2026-09-25.md (13 atendidas, 6 parciais, 1 não atendida), incluindo resultados negativos.

Acúmulo de Ground Truth (opt-in, LLM_ROUTER_GROUND_TRUTH=1) constrói um corpus de decisões de roteamento reproduzíveis em vez de telemetria não vinculada; desativado por padrão, pois é a única parte que grava texto de prompt em disco. Detalhes: guide/GROUND_TRUTH.md.

---

Documentação

Índice completo: guide/README.md

Documento	Propósito
Início Rápido (2 min)	Caminho mais rápido para roteamento funcional
Introdução	Passo a passo completo de configuração
Matriz de Suporte de Hosts	Comparação de recursos por host
Provedores	Configuração de provedores e recomendações de modelos
Políticas de Roteamento	routing.yaml esquema e criação da sua própria política
Referência de Ferramentas	Todas as ferramentas MCP com exemplos
Arquitetura	Design interno e estrutura de módulos
Solução de Problemas	Problemas comuns e correções
Testando o Roteador	Suíte de isolamento para verificar a saúde do roteamento
Medição	O que "economia" significa e como é calculada
RouterArena	Metodologia de benchmark, resultados e descobertas negativas
Ground Truth	Corpus de roteamento reproduzível, opt-in
Benchmarks	Tabela de custo/latência/qualidade de modelos, regenerada por CI
Changelog	Notas de versão (arquivo)

llm-router é pontuado no benchmark RouterArena — divisão completa, 8.400 consultas, avaliado localmente com o harness deste repositório, ainda não verificado de forma independente. Pontuação atual da Arena: 72.35. Metodologia completa e resultados negativos (incluindo uma divisão de proxy que enganou o ajuste em 4,25 pontos): docs/ROUTERARENA.md.

---

Empresarial, Contribuição, Licença

llm-router é construído para desenvolvedores individuais e pequenas equipes: economia de custo local, zero sobrecarga de operações, nada hospedado. Para aplicação de políticas em toda a equipe, exportação de auditoria, SSO ou orçamentos por organização, veja Chuzom — um produto separado, irmão.

Contribuições são bem-vindas — veja CONTRIBUTING.md.

git clone https://github.com/ypollak2/llm-router.git
cd llm-router
uv sync --extra dev
uv run pytest tests/ -q         # Run tests (10,000+)
uv run ruff check src/ tests/   # Lint

Licença MIT. Issues · Discussões · PyPI · Changelog