Skill token-router, um roteador local sem perdas que economiza 99% do custo de tokens do Codex e Claude Code usando o modelo Gemma4 2b
(github.com/sleeplesshan)Olá,
Para quem costuma usar agentes de IA como Claude Code ou Codex para analisar logs grandes ou modificar código legado e sofre com o custo de tokens e a latência subindo rapidamente, quero compartilhar um skill que eu criei.
É o token-router, um roteador híbrido de contexto para lidar com arquivos grandes com a ideia de "exploração grátis localmente, inferência de alto desempenho na nuvem".
🛑 Que problema ele resolve?
Quando você envia logs de implantação de infraestrutura com mais de 2.000 linhas ou arquivos enormes de código-fonte inteiros para um LLM na nuvem, há um enorme desperdício de tokens de entrada e o tempo de espera também aumenta.
Para economizar, às vezes se usa um modelo pequeno para resumir o código antes, mas isso é arriscado. No momento em que uma linha de erro ou uma definição de variável fica de fora, a IA na nuvem perde o contexto e pode gerar uma resposta errada e sem sentido.
Além disso, nas versões mais recentes, expandi o roteamento para incluir também arquivos estáticos longos de instruções de agente repetidos a cada turno, como CLAUDE.md, AGENTS.md e .cursorrules. No entanto, como não é possível reduzir depois o custo de tokens de arquivos root longos que já foram injetados automaticamente, a recomendação é manter os arquivos de instruções root curtos e separar regras longas específicas de tarefas em arquivos de referência, roteando-os apenas quando necessário.
🧠 Como ele resolve isso? (como funciona na visão do usuário)
Esta ferramenta não resume o texto; ela usa rigorosamente uma abordagem de recortar apenas o trecho necessário do conteúdo original.
- Triagem local (Local Triage): roda no seu computador usando, via Ollama, o leve modelo Gemma 4 2B. Esse modelo local encontra rapidamente apenas os números exatos das linhas (coordenadas) que correspondem à pergunta do usuário.
- Extração do original (Raw Slicing): um script em Python recorta do disco, com base nesses números de linha, trechos limpos do texto original exatamente como estão.
- Inferência na nuvem (Reasoning): o modelo principal na nuvem recebe apenas os trechos originais de alta densidade, já sem ruído desnecessário, junto com um mapa da estrutura do arquivo, e pode se concentrar em depuração e escrita de código.
Como o conteúdo enviado é o texto original sem qualquer processamento, é possível aproveitar 100% da capacidade de raciocínio do modelo na nuvem, reduzindo drasticamente apenas o custo.
Atualmente, há suporte a três modos: error_log, heavy_code e agent_context. O agent_context é um modo que busca apenas as linhas originais relevantes para a tarefa atual em documentos de referência de instruções de agente, como CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules e agent-context/*.md.
📊 Resultados testados no meu PC
- Log grande de infraestrutura (2.000 linhas): o contexto de entrada caiu de 41.711 tokens para 131 tokens (99,69% de economia, tempo de processamento de 5,37 segundos).
- Código-fonte legado com bug (2.155 linhas): um conteúdo originalmente com 7.520 tokens foi enviado comprimido em apenas 70 tokens (99,06% de economia, tempo de processamento de 4,46 segundos).
🛠️ Pontos práticos que foram convenientes no uso real
- Evita travamentos no PC: se você tem receio de que usar IA local deixe o computador lento, esta ferramenta libera o modelo local da memória VRAM imediatamente no exato momento em que a extração das coordenadas de roteamento termina.
- Expansão inteligente de contexto para trás: se o trecho de código recortado ficar estreito demais e dificultar entender as dependências antes e depois, a IA na nuvem não responde no chute; há uma proteção no prompt para que ela peça de volta ao script que "recorte novamente uma faixa mais ampla".
- Streaming de arquivos grandes: mesmo que o arquivo seja grande demais e ultrapasse a capacidade de memória do modelo local, uma lógica de streaming no backend entra em ação automaticamente, primeiro examinando palavras-chave e o final do arquivo, o que torna o processo seguro.
- Suporte ao Claude Code: a versão mais recente também inclui um bootstrap compacto de
CLAUDE.mdpara Claude Code. Instruções longas específicas do Claude podem ficar em arquivos de referência separados e ser roteadas comagent_context.
Está totalmente disponível de graça sob licença MIT e pode ser registrado para uso imediato como script independente ou no formato de skill do OpenAI Codex. No Claude Code, também é possível chamar o mesmo script roteador consultando o bootstrap de CLAUDE.md. Espero que isso ajude na produtividade de desenvolvimento de quem trabalha com depuração de logs grandes ou código pesado com frequência.
Agradeço muito qualquer feedback ou opinião sobre arquitetura e otimização de prompts!
2 comentários
É uma boa skill, testei de leve.
Ao gerar o JSON para enviar em Python, às vezes ocorriam casos de erro por quebrar a sintaxe do JSON; quando troquei para 4b ou qwen2.5-coder:7b para usar, a taxa de erros caiu de forma perceptível.
Nossa, muito obrigado por testar logo após eu publicar e ainda deixar um feedback tão específico, incluindo comparações por porte de modelo!
Como você comentou, modelos ultrapequenos da faixa de 2B às vezes parecem ter a limitação de quebrar as restrições do system prompt e gerar JSON com sintaxe inválida em ambientes com logs complexos ou caracteres especiais misturados. Se houver folga de recursos de VRAM, realmente parece que a linha Qwen 2.5 Coder 7B ou Gemma 4B consegue extrair as coordenadas de roteamento com muito mais estabilidade.
Se mais alguém encontrar erros de sintaxe JSON durante os testes, talvez seja mais útil tentar executar trocando para um modelo maior via configuração de variável de ambiente, assim:
OLLAMA_MODEL=qwen2.5-coder:7b python3 scripts/router.py ...
Obrigado por compartilhar uma opinião de benchmark prático tão valiosa.