🪟 ThinWindow [Plugin do Claude Code - Agent Skill - Node.js - Benchmarking]

ThinWindow faz agentes de código lerem menos. É distribuído ao mesmo tempo como plugin do Claude Code e como Agent Skill: um conjunto curto de regras de leitura carregado no início da sessão, mais hooks que aplicam a parte cara dessas regras na própria chamada da ferramenta, antes que um arquivo de 2.000 linhas chegue à janela de contexto. Em 112 execuções de benchmark sobre três modelos, cortou de 13% a 23% do total de tokens, com o mesmo sucesso no Opus e no Sonnet. Sem dependências, sem telemetria, licença MIT.

Ver no GitHub Documentação

---

A conta é o que o agente carrega, não o que ele escreve:

Um agente de código não paga principalmente pelas respostas. Paga pelo contexto. Cada arquivo que abre, cada log de instalação que imprime e cada grep amplo que roda é anexado à conversa, e a conversa inteira é reenviada a cada turno seguinte. O custo de uma sessão se parece mais com

tokens ≈ tamanho do contexto × turnos

do que com o tamanho da resposta. Nas execuções base do benchmark, de 87% a 96% de cada token cobrado foi uma leitura de cache: contexto reenviado, turno após turno. A saída do próprio agente ficou abaixo de 2%.

Essa proporção é o argumento inteiro. Pedir brevidade ao agente mexe na coluna de ~1%. Impedir que ele puxe um arquivo de 2.000 linhas para a janela no turno 3 mexe na de ~90%, nesse turno e em todos os seguintes.

Medido em repositórios reais e publicado por inteiro:

Cada execução é um agente resolvendo uma tarefa do zero, em um clone novo de um repositório open source real — click ou commander.js — fixado em um commit, com as dependências instaladas antes de o agente começar, para que os logs de instalação não sejam cobrados de nenhuma das duas condições. A condição base usa o Claude Code sem modificações; o ThinWindow usa o mesmo mais o plugin. Nada além disso muda. Uma verificação oculta, que o agente nunca vê, decide se a execução deu certo.

A tabela acima não é uma captura nem um número copiado à mão: ela é lida dos dados do benchmark no repositório toda vez que esta página é compilada, e de novo no seu navegador, então reflete a última execução publicada e não o dia em que escrevi este post.

Um skill e um plugin, e por que os dois são necessários:

São duas camadas da mesma coisa, não dois produtos.

• O Agent Skill é a camada de instruções. O SKILL.md carrega um arquivo de regras mantido abaixo de 500 tokens: localizar com grep antes de ler, ler intervalos de linhas em vez de arquivos inteiros, não reler o que já está em contexto, limitar a saída dos comandos, fazer a menor mudança que funcione e encerrar com no máximo três linhas. É portátil: qualquer agente compatível com Agent Skills instala com npx skills add thinwindow/thinwindow, e os agentes que leem AGENTS.md podem colar as mesmas regras lá.

• O plugin do Claude Code é a camada que faz valer as regras, e ele já inclui esse mesmo skill. Além das regras, registra hooks que rodam na chamada da ferramenta, antes de o resultado chegar ao contexto: um Read completo de um arquivo com mais de 400 linhas volta como as primeiras 120 linhas mais um índice numerado; reler um arquivo sem alterações que já está em contexto é recusado; instalações, builds e testes passam pelo thinwindow-run, que manda o log completo para um arquivo temporário e devolve o código de saída, o final do log e as linhas de erro; cat de um lockfile, git log sem -n, ls -R, tree sem -L e find sem limite recebem uma alternativa mais barata.

As regras são aplicadas por hooks em vez de ficarem sob responsabilidade do modelo, porque uma regra que o agente pode esquecer sob pressão não é uma regra. E como os hooks interceptam a chamada em vez de corrigir o agente depois, aplicá-las não custa um turno. Instalar o plugin dá as duas camadas; instalar só o skill dá a metade portátil.

Todo hook falha em modo aberto: qualquer erro dentro do ThinWindow deixa a chamada passar intacta, e repetir uma chamada recusada também a deixa passar, então o agente nunca fica travado. Com THINWINDOW=off tudo é desligado.

Instalação:

# Claude Code — regras e hooks
/plugin marketplace add thinwindow/thinwindow
/plugin install thinwindow@thinwindow

# Qualquer agente com Agent Skills (Codex, Cursor, Copilot, Gemini CLI, OpenCode) — só as regras
npx skills add thinwindow/thinwindow

Stack Técnico:

• Runtime: Node.js 18+, ESM, zero dependências em execução. Os hooks são scripts locais que leem uma chamada de ferramenta e devolvem uma decisão.
• Distribuição: um marketplace de plugins do Claude Code, o padrão Agent Skills e um adaptador AGENTS.md simples.
• Estrutura do benchmark: um runner que clona repositórios fixados em um commit, executa claude -p nas duas condições, roda uma verificação oculta e registra tokens, custo, turnos e o rastro completo de chamadas de ferramentas como uma linha JSON por execução.
• Relatórios: cada número publicado — os READMEs, o site de documentação e a tabela desta página — é gerado a partir desses arquivos brutos. O CI falha se algum deles ficar desatualizado.
• Privacidade: não há nenhum código de rede. Sem analytics, sem relatórios de erro, sem checagem de atualização.

Verifique em vez de acreditar:

Cada execução é uma linha de JSONL em bench/results/, com o modelo, a versão do Claude Code, o commit do ThinWindow, as contagens brutas de tokens e o rastro de ferramentas. Nada é excluído: as execuções que falharam continuam nas tabelas. Para rodar na sua própria conta:

node bench/run.mjs --condition baseline,thinwindow --reps 3 --model sonnet --dry-run
node bench/run.mjs --condition baseline,thinwindow --reps 3 --model sonnet --max-cost 10
node bench/report.mjs

O que os números não dizem:

O benchmark é publicado de propósito com os limites à mostra, porque uma medição sem eles é marketing:

• É restrito. Oito tarefas, duas bibliotecas de parsing de argumentos de linha de comando, três modelos, em JavaScript e Python — e as regras foram ajustadas nessas mesmas tarefas. Dá para mostrar uma direção, não para prometer uma porcentagem a ninguém.
• A contabilidade de tokens é volátil. Versões de modelo, prompts do harness, taxa de acerto de cache, ferramentas habilitadas, tamanho do repositório e a sorte do dia podem mexer num resultado mais do que o efeito medido aqui. Por isso as tabelas mostram medianas e dispersão por tarefa, e não uma única média de manchete.
• Nem toda tarefa melhora. No Sonnet 5, três das oito tarefas saíram mais caras com o ThinWindow do que sem ele. Essas regressões são publicadas em vez de descartadas, e são o caminho mais claro que resta para números melhores.
• Os resultados vão envelhecer, e serão medidos de novo em vez de ficarem parados.

Conclusão:

O ThinWindow começou como uma ferramenta pessoal para baratear minhas próprias sessões com agentes, e foi publicado porque as medições pareciam mais úteis do que a opinião por trás delas. O projeto demonstra:

• Construir contra o modelo de custo real — contexto reenviado por turno — em vez do intuitivo.
• Condicionar o comportamento do agente no limite da chamada de ferramenta, pela API de hooks do Claude Code, com um desenho que falha em modo aberto e nunca pode bloquear uma chamada.
• Publicar a mesma base de código como plugin do Claude Code e como Agent Skill portátil, para que as regras sobrevivam a qualquer harness específico.
• Projetar um benchmark de agentes reprodutível: repositórios fixados, verificação oculta, execuções sequenciais, resultados brutos versionados e regressões incluídas.
• Tratar cada número publicado como saída gerada, com um CI que falha quando a documentação se descola dos dados.

---