Claude Code Mods: acompanhe o contexto e reveja edições sem confundir sinais com validação

Em uma sessão longa do Claude Code, normalmente surgem duas perguntas diferentes: quanto o contexto cresceu depois do último turno e quais operações de edição de arquivo Claude chegou a chamar. O playground da Anthropic oferece um exemplo pronto para cada caso. Token Weather mostra o uso do contexto da sessão principal; Replay Theater permite percorrer as chamadas de edição do último turno que alterou arquivos.

O limite essencial é simples: os dois dão observabilidade, mas não fazem a validação final. Um percentual de contexto não é saldo, custo nem conclusão da tarefa. Uma edição no replay não prova que você a aprovou, que a ferramenta funcionou ou que o arquivo final ainda contém a mudança.

Escolha o Mod pela pergunta que precisa responder

Pergunta	Carregue primeiro	O que ele mostra	O que não prova
Quanto da janela principal está ocupado e houve crescimento brusco nos últimos turnos?	Token Weather	Context tokens, tamanho da janela, percentual e tendência de 12 turnos	Saldo da assinatura, cobrança, requisições restantes ou tarefa concluída
Quais chamadas Edit, Write ou MultiEdit ocorreram no último turno com edição?	Replay Theater	Arquivo, ferramenta, fragmentos locais antes/depois e diff curto	Aprovação, sucesso da ferramenta, estado final do disco ou testes aprovados

Para diagnóstico, carregue um por vez. Os dois exemplos podem desenhar em AbovePrompt. Os READMEs informam que essa faixa é compartilhada; quando outro Mod usa o mesmo espaço, apenas um pode ficar visível.

Confira versão e confiança antes de executar

Os READMEs atuais dos exemplos exigem Claude Code 2.1.287 ou posterior e são voltados ao terminal. Confira o cliente:

claude --version

Esses Mods estão no playground da equipe Anthropic DevRel. O repositório os oferece como exemplos no estado atual, sem suporte ou garantia de continuidade quando Claude Code, API ou modelos mudarem. Antes de rodar, leia README.md, .claude-plugin/plugin.json, hooks/hooks.json e o módulo de hooks do diretório escolhido.

Um Mod executa com as permissões do seu usuário; “só desenha interface” não é uma barreira de segurança. Na primeira tentativa, prefira --plugin-dir por uma única sessão. Ao fechar esse processo do Claude Code, o experimento termina e não vira uma instalação persistente.

Clone os exemplos oficiais e valide o escolhido

git clone https://github.com/anthropics/claude-code-playground.git
cd claude-code-playground/claude-code/mods

Baixar o repositório não comprova que a estrutura está válida. Valide o diretório exato antes de iniciar.

Para Token Weather:

claude plugin validate ./token-weather
claude --plugin-dir ./token-weather

Para Replay Theater:

claude plugin validate ./replay-theater
claude --plugin-dir ./replay-theater

Se validate apontar erro, pare e restaure o manifest, a configuração de hooks ou o módulo indicado. Não prossiga supondo que Claude Code ignorará com segurança um pacote quebrado. Na nova sessão, /plugin ajuda a confirmar o que foi carregado. O sinal operacional vem depois: Token Weather precisa atualizar após um turno concluído do loop principal; Replay Theater precisa de um turno concluído que realmente invoque edições de arquivo.

Leia Token Weather como telemetria de contexto, não como fatura

Depois de cada turno principal, Token Weather chama $.session.usage() e lê tokens, window e percent em context. Ele desenha uma linha acima do prompt, mantém as 12 leituras mais recentes e mostra quanto o último turno acrescentou.

Os campos significam:

• tokens: contexto de entrada usado para responder a última vez, somando input sem cache, gravado em cache e lido de cache;
• window: janela de contexto do modelo da sessão;
• percent: relação tokens / window.

Uma leitura de 0% antes da primeira resposta é esperada, pois ainda não houve usage informado. A faixa atualiza uma vez após o turno, não continuamente durante a execução. Turnos de subagentes não geram uma leitura separada do loop principal.

Por que o percentual pode divergir do aviso de compactação

Token Weather divide pela janela completa de contexto. O aviso auto-compact do Claude Code usa um ponto de compactação menor, então os percentuais podem divergir. Em uma captura oficial do exemplo, Token Weather marcou 81% enquanto o cliente mostrou 90%. Isso demonstra duas escalas sob as condições do exemplo, não valores que devam coincidir na sua sessão.

As barras do histórico são relativas à maior leitura exibida. Por isso, variações podem parecer grandes mesmo com percentual absoluto baixo. Para leitura absoluta, use percentual e número de tokens. O histórico reinicia quando a sessão começa ou o plugin é recarregado.

Qual conclusão Token Weather sustenta

Você pode dizer: “O contexto de entrada da sessão principal cresceu bastante nos últimos turnos.” Não pode concluir: “Minha conta tem 19% restante”, “este turno custou determinado valor” ou “a tarefa terminou”. Cache muda o tratamento de cobrança, mas o input em cache ainda ocupa contexto. Consulte saldo, cobrança e status no registro do provedor.

Use Replay Theater para inspecionar tentativas de edição

Depois de carregar, peça uma tarefa que realmente modifique arquivos e espere o turno terminar. Quando a dica aparecer, abra o replay:

/replay

Também é possível focar a faixa com ctrl+x, Tab e pressionar r. No painel:

Tecla	Ação
n	Próximo passo
p	Passo anterior
c ou Escape	Fechar

Cada passo mostra arquivo, ferramenta, linhas adicionadas/removidas e um diff curto. O exemplo limita cada passo a 12 linhas. Em Edit, compara old_string com new_string, não o arquivo inteiro, e não mostra números de linha. Em Write, lê o conteúdo antigo do disco imediatamente antes da chamada; arquivos acima de 400 linhas aparecem sem correspondência completa.

Por que uma edição do replay pode não existir no arquivo final

Replay Theater registra a chamada antes de encaminhá-la. Uma edição negada por você ou uma chamada que falhou ainda pode aparecer. Uma chamada posterior também pode sobrescrever ou reverter a anterior.

O replay fica na memória da sessão atual. Reiniciar Claude Code ou recarregar o plugin o remove. Um turno posterior sem edições preserva o replay anterior. Use-o para entender “o que Claude tentou”, não como retrato do repositório final.

Valide o trabalho nos arquivos reais

Independentemente do replay, termine no repositório:

git status --short
git diff --stat
git diff -- path/to/file
git diff --check

git status --short mostra adições, alterações e exclusões reais. git diff --stat revela um escopo amplo inesperado. Leia o diff completo dos arquivos importantes em vez do recorte de 12 linhas. Rode git diff --check para erros de espaços e depois o menor teste, type check ou build diretamente relacionado aos arquivos alterados.

Escreva critérios observáveis: “a função alvo foi renomeada, todas as referências foram atualizadas, o teste relevante passa e nenhum arquivo alheio mudou”. “O replay mostrou cinco passos verdes” não é critério de aceitação.

Confirme uso real no registro do provedor

Token Weather mostra o preenchimento do contexto; não calcula a fatura da API. Com qualquer provedor, encontre a requisição por horário e modelo e confira status, input/output tokens, cache tokens aplicáveis e cobrança registrada.

Quando BetterToken é a rota de API do Claude Code, a página atual informa que model, time, token counts, cache usage, final cost e status permanecem juntos em um registro de requisição. Use esse registro para conferir o uso real. Isso não significa que BetterToken forneça os Mods, armazene prompt/resposta completos ou aceite automaticamente a mudança. A conexão está na documentação BetterToken para Claude Code.

Solucione problemas na ordem mais curta

claude plugin validate falha

Leia o arquivo e campo exatos citados pelo validador. Confirme que está em claude-code-playground/claude-code/mods, que o downloader não renomeou arquivos ocultos e que o checkout está íntegro. Revalide antes de iniciar.

Token Weather não aparece ou fica em 0%

Use o terminal, não apenas o chat do VS Code; confirme versão 2.1.287 ou posterior e o Mod correto na sessão. Envie uma requisição normal e espere o turno principal terminar. Zero antes da primeira resposta é normal.

Replay Theater não mostra a dica

Confirme que o turno chamou Edit, Write ou MultiEdit e já terminou. Ler arquivos, responder uma pergunta ou executar apenas comandos Bash não cria uma etapa de edição para ele registrar.

Replay e git diff discordam

Confie nos arquivos. A edição pode ter sido negada ou falhado, uma chamada posterior pode substituí-la, o painel mostra apenas um fragmento local ou restart/reload alterou o estado em memória. Revise o diff completo e os testes direcionados.

Dois Mods não aparecem juntos

Desative um e inicie nova sessão com o outro. Como ambos usam AbovePrompt, a falta da segunda faixa não prova que o pacote esteja quebrado.

O ciclo mínimo confiável

Escolha Token Weather para investigar crescimento de contexto e Replay Theater para identificar chamadas de edição. Carregar com sucesso é apenas o primeiro passo; ver o medidor ou replay é o segundo. O terceiro sempre é inspecionar os arquivos reais, executar a menor validação relevante e, quando o consumo importar, conferir o registro do provedor. Assim, visibilidade do processo vira resultado confirmado.