Computer use no Claude Code: menos tokens a cada leitura do desktop

Por que computer use gasta tantos tokens

Um agente que controla um app do desktop trabalha em ciclo: lê a janela, age num elemento, lê a janela de novo para conferir. Cada leitura entra no contexto, e quase tudo é igual à leitura anterior.

Ler a árvore de acessibilidade em JSON já é bem menor que uma imagem da tela. Mas o JSON repete o nome de cada chave, as aspas e o id da leitura dentro de cada ref, e a releitura repete a janela inteira para mostrar que um botão mudou.

Passo um: a visão compacta

O Downshift passa agent-desktop snapshot e agent-desktop find pelo downshift compact e imprime uma linha por elemento, indentada pela profundidade. Os refs viram eN sob uma legenda, a lista de ações que a maioria dos elementos tem aparece uma vez, e estados, posições, ids nativos e classes ganham formas curtas. Campo sem forma curta vai como JSON, então nada se perde. Um teste decodifica a visão de volta para o mesmo JSON.

agent-desktop snapshot (envelope 2.6) app="Chat" complete=true ref_count=175 snapshot_id="s9x0lmz4"
refs: eN means @s9x0lmz4:eN
actions: an eN line without actions= has Click; actions=- means none
window "general - Acme - Chat"
  group "Sidebar"
    tree "Channels"
      e5 treeitem "# general" [selected] .sidebar-item
  group "Channel"
    e174 textfield "Message #general" actions=Click,SetFocus .editor ph="Message #general"
    e175 button "Send now" [disabled]

Passo dois: só o que mudou

A ferramenta numera os elementos do mesmo jeito enquanto a janela não muda; só o id da leitura é novo, e refs antigos continuam válidos. Então uma linha igual nas duas visões é o mesmo elemento com o mesmo ref. Uma releitura da mesma janela, em até 10 minutos, volta só com as linhas que mudaram:

delta from snapshot s9x0lmz4 (same window, read 4s ago): 2 of 212 lines changed.
@@ line 211
     e174 textfield "Message #general" actions=Click,SetFocus .editor ph="Message #general"
-    e175 button "Send now" [disabled]
+    e175 button "Send now"
[downshift compact: compacted 26839 to 668 bytes; full output: downshift retrieve d3bb124d09d8]

O delta só vai quando as duas leituras estão completas, a leitura bruta está guardada localmente para o downshift retrieve trazer inteira, e o delta tem menos de 60% da visão. Senão, vai a visão completa.

Quanto fica menor

Medido com o binário downshift em leituras sintéticas montadas no formato de saída da ferramenta, não num desktop real. Os bytes incluem a linha de marcador.

As flags -i, --compact e --skeleton da própria ferramenta encolhem a árvore antes; o Downshift soma por cima. Cada leitura conta no downshift report, no downshift stats e no painel de sessão, com os bytes lidos de volta pelo retrieve descontados.

Como ativar

No Claude Code com o hook do Downshift não há nada a fazer: a leitura é reescrita sozinha. Em qualquer outro harness, ou num script, o agente roda a leitura pelo compactor, e os dois passos valem:

downshift compact -- agent-desktop snapshot --app Files -i

Defina DOWNSHIFT_DESKTOP_DELTA=0 para mandar toda leitura inteira. A forma MCP da ferramenta não é compactada, porque o Downshift não vê resultados de MCP.

Limites

• Agentes que dividem uma sessão, ou chamadas diretas do mesmo diretório, dividem o escopo do delta. Um agente pode receber um delta de uma leitura que não viu; o delta avisa e aponta o downshift retrieve.
• Um elemento novo no começo da árvore renumera os refs depois dele, e vai a visão completa.
• Todos os números aqui vêm de leituras sintéticas. Rode a mesma tarefa com DOWNSHIFT_EXEC=0 e com o hook ligado, e compare o downshift report.

Perguntas frequentes

O Downshift tira print ou controla o desktop?

Não. O Downshift não instala nem roda um controlador de desktop. Ele só encurta o que o agent-desktop imprime quando o agente lê a tela.

Algo se perde na visão compacta?

Nenhum campo. Um teste decodifica a visão de volta para o mesmo JSON, e a leitura bruta fica a um downshift retrieve de distância.

Funciona fora do Claude Code?

Sim. O Claude Code reescreve a leitura sozinho. Nos outros harnesses o agente roda downshift compact -- agent-desktop snapshot ..., e o delta usa o diretório de trabalho como escopo.

Quanto economiza?

Em leituras sintéticas, de 53% a 60% numa primeira leitura, cerca de 97% numa releitura depois de uma ação, e 84,9% num ciclo ler, agir, conferir de três leituras. Ainda não foi medido num desktop real.

Guias relacionados

• Saída longa de teste e build no Claude Code: por que gasta contexto e como cortar
• Economizar tokens no Claude Code: o que funciona de fato
• Subagentes do Claude Code gastam o limite mais rápido?

Fontes

1. Guia do Downshiftmedido
   docs/pt-br/guias/agent-desktop.md
   como a visão e o delta funcionam, as condições e os limites
2. Fixtures do Downshiftsintético
   internal/compressor/testdata/corpus
   as leituras por trás da tabela, montadas no formato de saída da ferramenta; medidas com o binário downshift em 2026-11-09
3. Teste de ida e voltamedido
   agent_desktop_roundtrip_test.go
   decodifica a visão compacta de volta para o mesmo JSON