Há cerca de seis meses, comecei a usar o Claude Code no plano Pro, que me custava US$ 20 por mês. Em poucos dias de trabalho, eu já esgotava o limite semanal sem entender por quê. Era como uma mesa cheia de papéis: eu precisava de uma informação, mas o restante ocupava espaço.
Foi dessa dor que nasceu o Downshift, meu projeto open source em Go e um dos mais importantes da minha carreira. As principais funcionalidades são:
- Compactor: encurta resultados de comandos antes que a IA os leia, preservando erros e códigos de saída. No Computer Use, quando o agente opera aplicativos, também compacta as descrições de tela do Agent Desktop e pode enviar apenas o que mudou entre leituras da mesma janela.
- Model-routing: aplica regras para escolher o modelo e quanto esforço ele deve dedicar às tarefas recebidas pelos subagentes, os agentes auxiliares. A escolha considera a política definida, os modelos disponíveis e o suporte da ferramenta utilizada.
- Agents: reúne perfis especializados e skills, instruções reutilizáveis para atividades como pesquisa, implementação, revisão e segurança. Eles orientam como dividir o trabalho e o que cada agente deve entregar.
- Telemetry: permite acompanhar sessões, escolhas de modelos e resultados da compactação. Esses dados ajudam a enxergar onde os recursos estão sendo usados e o que vale otimizar.
O projeto está em beta. O código e a documentação estão no GitHub. Já há resultados em cenários específicos, mas ainda falta medir quanto eles prolongam o uso do plano Pro no dia a dia.
O que precisei estudar para construir o Downshift
Para entender esse consumo, precisei estudar contexto, o conjunto de informações que o modelo recebe, e tokens, as unidades de texto que ele processa. Uma pergunta curta pode carregar arquivos, histórico e resultados de comandos, como explica a documentação do Claude Code. A engenharia de contexto, apresentada pela Anthropic, trata de como escolher e organizar esse material.
Também estudei como dividir tarefas entre agentes e escolher modelos e níveis de esforço. Building effective agents é uma referência para essa arquitetura. Junto disso vieram os testes: uma saída menor precisa continuar dando ao agente condições de executar a tarefa. Essa relação entre otimização e qualidade aparece em Demystifying evals for AI agents.
Como reduzir o consumo de tokens no Claude Code
Ao construir o Compactor, percebi que boa parte do tratamento das saídas dos comandos podia ser feita por funções em Go: reconhecer formatos, contar testes e separar o que passou do que falhou. Esse processamento segue regras e acontece localmente, sem chamar um modelo de IA para resumir o resultado. A informação já chega mais enxuta ao agente.
Exemplo didático: você pede ao agente para corrigir uma falha em um projeto Go. Ele investiga o código, faz a alteração e executa os testes. A resposta do terminal também entra no contexto. É nessa etapa que o compactador pode entregar uma versão mais curta, preservando o código de saída e os detalhes de falhas.
No Claude Code configurado, o hook encaminha comandos compatíveis e associa a execução à sessão. Para experimentar a compactação manualmente, fora desse fluxo:
downshift compactor -- go test ./...
Uma execução local de 10 de novembro, com uma seleção de testes do Downshift e saída detalhada (go test -v), mostra a diferença. Trechos reais:
Antes:
=== RUN TestStripColour
--- PASS: TestStripColour (0.00s)
=== RUN TestScreenText
--- PASS: TestScreenText (0.00s)
Depois:
Go test -v: PASS (5 passed, 0 failed, 0 skipped) in 0.187s
Subtests: 16 passed or skipped under those tests
A entrega completa caiu de 2.006 para 271 bytes, incluindo a indicação de recuperação: 86,5% menos bytes nessa execução. O original pôde ser recuperado com downshift retrieve ID_DA_SUA_SAIDA. É uma demonstração local; esse percentual não mede tokens nem duração do plano Pro.
O padrão passa a ser balanced: cortes com perda só acima de um limite de tamanho, sempre com a saída completa recuperável via retrieve. O lossless é a opção conservadora, sem cortes com perda; o aggressive faz cortes mais intensos. Nas minhas medições mais recentes no Claude Code, usei lossless; antes, usava balanced.
Também há situações em que o Compactor devolve a saída inteira. Por exemplo: em uma execução de testes com falha, uma linha que o parser não reconhece antes do bloco de erros pode impedir a compactação. O agente recebe o resultado original, com os detalhes necessários para investigar. Esse comportamento está descrito na documentação de compactação de testes com falha.
Roteamento de modelos: capacidade proporcional à tarefa
Na mesma correção, o agente principal pode delegar uma parte do trabalho a um subagente. Renomear uma variável e avaliar uma mudança de arquitetura exigem capacidades diferentes. O Downshift aplica as regras configuradas às escolhas do agente principal, considerando os modelos conhecidos da sessão.
Essa etapa acontece localmente, sem consultar outro modelo de linguagem. Quando não é possível estabelecer uma escolha segura, o modelo solicitado é mantido. O modelo da sessão principal permanece o mesmo.
Na sessão instrumentada, downshift session --why mostra a árvore de subagentes e seus motivos; downshift report reúne os dados de consumo disponíveis. Essas informações ajudam a investigar saídas e decisões de delegação antes de mudar a configuração. A chamada manual da demonstração acima não é associada à sessão nem entra nesse painel.
Computer Use: o “Opalão” no consumo de tokens
Outra descoberta foi como o Computer Use pode virar um “Opalão” no consumo de tokens. O agente consulta a interface, executa uma ação e precisa olhar de novo para conferir o resultado. Para trabalhar com o Agent Desktop, estudei as árvores de acessibilidade: estruturas que descrevem textos, botões e campos do aplicativo.
Pense em um formulário: depois de clicar em “Salvar”, o agente precisa conferir a confirmação. Receber toda a descrição da janela novamente repete informações que não mudaram. Na v0.13.0, de 9 de novembro, estendi a compactação a essas leituras: o Downshift encurta a primeira descrição e pode enviar só as alterações, chamadas de deltas, nas seguintes. A leitura completa continua recuperável. Com menos texto repetido no contexto, o agente pode gastar menos tokens para acompanhar a mesma interface.
Um teste sintético de três leituras registrou 84,9% menos bytes. A economia de tokens em um desktop real ainda precisa ser medida. A integração cobre leituras pela linha de comando do Agent Desktop; seus resultados via MCP não são compactados. Os detalhes estão no guia da integração.
Economia de tokens: o que os benchmarks demonstraram
No Claude Code, um estudo controlado com 46 execuções em quatro grupos registrou 24,1% menos tokens por execução aceita com roteamento, comparado ao modo nativo opusplan. O grupo roteado passou nos testes em 12 de 12 execuções; o controle, em 10 de 11. As tentativas que falharam entram na conta.
Esse resultado mede roteamento; o compactador estava desligado nos dois grupos comparados. Foram tarefas mecânicas delegadas, com um operador, em 21 de outubro, antes de mudanças posteriores no roteamento. O benchmark completo documenta a versão e o método.
No KiroCrew, um ensaio de uso real registrou até cerca de 53% menos tokens por tarefa, combinando roteamento e compactação. Foram seis tarefas de controle em uma sessão de várias horas: uma evidência preliminar, que não permite atribuir todo o ganho ao roteamento. Veja o registro e suas limitações.
Na compactação, o benchmark de 110 casos sintéticos registrou 67,1% menos bytes, com recuperação da saída completa habilitada. Bytes, tokens e custo são medidas diferentes. Esses percentuais vêm de cenários distintos e não devem ser somados.
Como instalar e testar o Downshift
Siga o guia de instalação e, no seu repositório, execute:
downshift setup
downshift doctor
O setup apresenta as mudanças antes de aplicá-las; o doctor verifica a configuração. Escolha uma tarefa recorrente, como a correção com testes do exemplo, e compare consumo, tempo para concluir e correções manuais com e sem Downshift. Inclua as tentativas que deram errado: o que importa é chegar a uma entrega aceita.
A integração varia entre Claude Code, Codex, OpenCode, Cursor e outros ambientes. Confira a matriz de suporte.
Fiz o Downshift com carinho, partindo de uma dificuldade minha e pensando em quem também passa por isso. Compartilhei o código e os aprendizados para que esse trabalho possa beneficiar outras pessoas também.
Fiquem à vontade para conhecer o projeto, experimentar e contribuir com ideias ou melhorias. Se usarem nos projetos de vocês, compartilhem os resultados: quero saber como ele funciona no dia a dia de cada um. Espero que seja útil para vocês. Façam bom proveito! 💚
Top comments (0)