🪟 ThinWindow [Plugin para Claude Code - Agent Skill - Hooks - Node.js - Medição]

O ThinWindow mantém fina a janela de contexto do Claude Code do primeiro prompt até a manhã seguinte. Ele corta leituras e logs desmedidos enquanto você trabalha, mostra o que cada requisição carrega e, quando você volta a uma sessão expirada, oferece recomeçar do zero a partir de um resumo curto em vez de pagar de novo pelo contexto antigo. É distribuído ao mesmo tempo como plugin para o Claude Code e como Agent Skill, e está listado no diretório oficial de plugins do Claude Code. Sem dependências, sem telemetria, MIT.

Ver no GitHub Documentação

---

O contexto é a conta:

Um agente de código paga mais pelo que carrega do que pelo que escreve. Três coisas movem a conta:

• Cada requisição reenvia a sessão inteira. Cada arquivo que o agente lê, cada log que imprime e cada resposta longa fica na conversa e é pago de novo, a partir do cache de prompts, em cada requisição seguinte.
• Uma sessão expirada é paga duas vezes. O Claude Code mantém o cache de prompts de uma sessão por até uma hora. Se você voltar depois disso, o próximo prompt escreve todo o contexto de novo ao preço de escrita de cache, muitas vezes o que custa lê-lo do cache.
• A configuração vai junto em cada requisição: o prompt de sistema, as definições de ferramentas, as listas de skills e de agentes, as instruções de MCP e os arquivos CLAUDE.md.

O ThinWindow atua nas três, nos quatro momentos de uma sessão.

Uma janela fina para a sessão inteira:

• No começo: saber o que cada requisição carrega.
  • Uma vez por semana e por projeto, quando a primeira requisição de uma sessão é grande, um aviso de uma linha mostra com quanto começa cada requisição e as suas maiores partes.
  • Um perfil opcional, o thinwindow-minimal, remove as ferramentas integradas que uma sessão de código focada quase nunca usa.
• Durante o trabalho: manter a janela fina.
  • Regras curtas pedem ao agente que localize antes de ler, leia só o trecho necessário, limite a saída dos comandos, e escreva e diga só o que a tarefa precisa.
  • Os hooks aplicam a parte cara na própria chamada. Ler inteiro um arquivo longo devolve o seu começo e um índice com números de linha. Instalações, builds e testes passam pelo thinwindow-run, que guarda o log completo num arquivo temporário e mostra o código de saída, o final e os erros.
• Entre sessões: retomar sem pagar duas vezes.
  • Um resumo de cada sessão é mantido a cada turno, sem chamar um modelo.
  • Quando você volta a uma sessão grande depois que o cache expirou, o seu primeiro prompt é segurado uma vez. Ao lado de recomeçar do zero, você vê o que continuar reescreve, em tokens e em US$ a preço de tabela.
  • /clear e depois /thinwindow:resume retoma a partir do resumo, e /thinwindow:brief pede ao agente uma passagem mais completa enquanto o cache ainda está quente.
• Depois: ver para onde foi o seu contexto. O /thinwindow:report lê as suas próprias transcrições na sua máquina e mostra quanto contexto cada requisição reenvia, o que as sessões expiradas reescreveram, o que a sua configuração carrega e a saída de qual ferramenta é mais reenviada. Só números agregados, e nada é enviado a lugar nenhum.

Uma skill e um plugin, e por que precisa ser as duas coisas:

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

• A Agent Skill é a camada de instruções. Ela leva as regras, abaixo de 2.000 caracteres, e o thinwindow-run. É portável: qualquer agente compatível com Agent Skills a instala com npx skills add thinwindow/thinwindow, e os agentes que leem AGENTS.md podem colar as mesmas regras.
• O plugin é a camada de aplicação, e traz essa mesma skill. Os seus hooks rodam nos quatro momentos acima: SessionStart para as regras, PreToolUse para os controles, Stop para o resumo e o aviso de configuração, e UserPromptSubmit para o aviso de sessão expirada.

As regras são aplicadas por hooks em vez de confiadas ao modelo, porque uma regra que o agente pode esquecer sob pressão não é uma regra. E como os hooks agem na chamada em vez de corrigir o agente depois, aplicá-las não custa um turno.

Todos os hooks falham abertos: qualquer erro dentro do ThinWindow deixa a chamada passar, e repetir uma chamada recusada também a deixa passar, então um agente nunca fica travado. THINWINDOW=off desliga tudo.

Onde funciona:

• Claude Code (terminal, IDE, a aba Code do app de desktop): tudo.
• Cowork:
  • funcionam as regras, o controle de leitura e o /thinwindow:brief;
  • o relatório cobre só a tarefa atual;
  • os resumos não passam de uma tarefa para outra;
  • nenhum dos dois avisos aparece.
• Chat (claude.ai e os apps): a Agent Skill, que o Claude carrega quando uma tarefa precisa dela, e o /thinwindow:brief.

Instalação:

# Pelo diretório de plugins
# (app de desktop do Claude: Customize → Plugins → Discover → ThinWindow)
claude plugin install thinwindow@anthropic-plugin-directory

# Claude Code, pelo repositório
/plugin marketplace add thinwindow/thinwindow
/plugin install thinwindow@thinwindow

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

Verificado, não suposto:

O ThinWindow é verificado com um método pensado para continuar barato à medida que os modelos mudam.

• Testes unitários para cada mecanismo, no CI em macOS, Linux e Windows.
• Repetições de sessões gravadas, sem custo de modelo, antes de construir qualquer coisa.
• Algumas execuções de agente direcionadas, com os critérios de aprovação escritos antes da primeira execução.
• Uma validação por versão contra o Claude Code sem o plugin.

Antes de publicar a 0.4.0, o método e as regras de aprovação foram publicados antes da primeira execução. Todas as tarefas do benchmark e todas as cadeias de retomada foram concluídas com o ThinWindow, assim como sem ele. Recomeçar do zero depois que o cache de prompts expirou custou menos por cadeia concluída do que continuar. As linhas brutas e as transcrições limpas dos agentes são públicas no repositório.

Stack técnica:

• Runtime: Node.js 18+, ESM, sem dependências de execução. Os hooks são scripts locais que leem uma chamada de ferramenta, um prompt ou o fim de um turno, e devolvem uma decisão.
• Integração com o Claude Code:
  • quatro eventos de hooks;
  • skills que o usuário invoca e que não acrescentam nada à lista de skills;
  • leituras limitadas e incrementais da transcrição da sessão;
  • um perfil que cada usuário ativa por conta própria.
• Distribuição: o diretório de plugins, um marketplace de plugins do Claude Code, o padrão Agent Skills e um adaptador AGENTS.md.
• Estrutura de medição:
  • repositórios fixados e verificação oculta;
  • um ambiente registrado por suíte;
  • ordem de execuções com semente e intervalos hierárquicos;
  • cadeias de retomada e transcrições limpas.
• Privacidade:
  • nenhum código de rede: nem analytics, nem relatórios de falhas, nem verificação de atualizações;
  • o relatório imprime só números agregados, e um teste verifica isso.

Conclusão:

O ThinWindow começou como uma ferramenta pessoal para baratear as minhas próprias sessões com agentes. Na 0.4.0, ele acompanha o custo ao longo da sessão inteira em vez de uma única chamada. O projeto demonstra:

• Construir sobre o modelo de custo real de uma sessão de agente: contexto reenviado em cada requisição, reescrito quando o cache expira, e uma configuração paga em cada turno.
• Usar a API de hooks do Claude Code em quatro momentos de uma sessão, com um design que falha aberto e nunca bloqueia uma chamada nem um prompt.
• Distribuir uma única base de código como plugin para o Claude Code e como Agent Skill portável, para que as regras sobrevivam a qualquer ambiente.
• Medir com disciplina: validação registrada antes, dados brutos publicados, falhas incluídas e afirmações limitadas ao que os dados sustentam.
• Respeitar a privacidade desde o design: tudo local, saída agregada e dados públicos limpos.

---