Compact Adviser: saiba quando usar /compact no Claude Code

O Compact Adviser responde a uma pergunta: devo rodar /compact agora? Ele foi escrito por Kun Chen (kunchenguid) e é distribuído para Claude Code, Pi, Codex CLI e Grok a partir de um único repositório. Esta página trata do mod para Claude Code em packages/claude-mod.

Compactar cedo demais joga fora contexto de que você ainda precisa; compactar tarde demais faz cada turno carregar um histórico longo. Depois de cada turno concluído, o mod verifica algumas condições locais baratas e, se elas passam, faz ao modelo Jev da TypeSafe duas perguntas curtas sobre a conversa: a última unidade de trabalho do assistente está concluída? O assistente fez o trabalho ele mesmo ou mais coordenou? As duas respostas são combinadas em uma pontuação. Se a pontuação passa de um limite, aparece uma linha de status: "work appears completed or recorded. Run /compact to save tokens."

O limite é rígido (0,90) enquanto o contexto está quase vazio e vai relaxando em direção a 0,50 conforme o contexto se aproxima do ponto de autocompactação do Claude Code, porque uma dica errada custa mais quando ainda há espaço. Se você optar pelo modo automático, o mod faz a compactação sozinho nesse checkpoint em vez de só dar a dica.

Ele precisa de uma chave de API da TypeSafe, que você mesmo fornece.

Uma dica real precisa de mais de 40.000 tokens de contexto e de uma chave da TypeSafe, o que não cabe em um vídeo curto. A gravação inicia o Claude Code com o mod carregado, executa /compact-adviser status (modo, mínimo, orçamento e estado da chave), depois abre o painel de configurações do /compact-adviser e vai até a linha da chave de API da TypeSafe, que mostra missing.

Use qualquer um dos métodos do bloco de instalação; os dois instalam direto do marketplace do autor. O mod não faz absolutamente nada a menos que o Claude Code seja iniciado com CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1, então inicie-o com essa variável e depois execute /compact-adviser para adicionar a sua chave da TypeSafe.

Tudo começa no hook turn.complete em hooks/register.ts:

on("turn.complete", async ($, e, next) => {
  const result = await next(e);
  if (!(await isActivated($)) || !interactive) return result;
  if (e.agentId !== undefined || e.reason !== "answer" || e.isAborted || !e.answer.trim()) {
    return result;
  }
  try {
    await settle($);
  } catch {
    notice($, "Compact adviser could not inspect this checkpoint; context left unchanged.");
  }
  return result;
});

Só conta um turno do loop principal que terminou com uma resposta de verdade; turnos de subagentes e turnos abortados são ignorados. settle conta a troca e aplica os filtros baratos: modo diferente de off, uma chave presente, contexto igual ou acima de minContextTokens e nenhum período de espera ou adiamento. Se passarem, ele agenda judgeCheckpoint com $.clock.after(0, …) para não atrasar o turno.

judgeCheckpoint monta um snapshot limitado a partir de $.session.messages() (veja lib/snapshot.ts), pula a requisição se a conversa tiver menos de 20.000 tokens ou se o mesmo checkpoint já tiver sido avaliado, e o envia para https://api.typesafe.ai/v1/systemone com $.http.fetch. A requisição expira após 2 segundos, e um erro, um timeout ou uma resposta malformada nunca contam como sim: o mod espera mais antes de tentar de novo e mostra um toast. Quando a pontuação é suficiente, o modo de dica chama $.ui.status com a dica, e o modo automático chama $.session.compact com instruções para manter exatos o trabalho atual, as tarefas pendentes e o próximo passo.

Qualquer compactação, sua ou do Claude Code, zera o período de espera da sessão pelo hook session.compact.

Execute /compact-adviser para abrir o painel de configurações, ou use os subcomandos: auto, hint e off trocam o modo; threshold 60000 define o contexto mínimo; budget 450000 define um orçamento de contexto contra o qual o limite é medido, em vez do ponto de autocompactação; snooze pula as próximas três trocas; dismiss apaga a dica atual; status mostra o estado atual. O modo, o mínimo, o orçamento e o registro de requisições também são linhas no /config. Um perfil de avaliação (JSON na configuração profile) pode mudar as perguntas, o peso da pontuação ou o cronograma do limite.

Lemos o register.ts, todos os arquivos em lib/, plugin.json, hooks.json, package.json e os helpers de teste antes de rodar qualquer coisa.

• Rede: o mod envia uma requisição por checkpoint qualificado para https://api.typesafe.ai/v1/systemone, um serviço de terceiros, com a sua chave no cabeçalho Authorization. O corpo é um snapshot da conversa recente, com no máximo 32.000 bytes, depois de ocultar na medida do possível padrões de chaves e os arquivos .env, auth.json, id_rsa/id_ed25519, .pem e .key. TYPESAFE_BASE pode apontá-lo para outra base https, ou para uma http de loopback. Instalar o plugin é tratado como consentimento para enviar isso quando há uma chave disponível, então coloque o modo em off para trabalhos que não podem sair da sua máquina.
• Arquivos: ele lê o .env na pasta da sessão para procurar TYPESAFE_API_KEY. Ele só grava quando você liga o registro de requisições: ~/.claude/compact-adviser-requests-<session-id>.jsonl, que nunca contém a chave.
• Configurações: salvar pelo painel grava as linhas de userConfig do próprio plugin via $.config.set. A chave salva fica oculta no /config.
• Compactação: só no modo automático, depois de um diálogo de confirmação exibido uma única vez.

Não há scripts de instalação, nem código empacotado ou minificado, nem telemetria além da própria requisição à TypeSafe.

Validado com o Claude Code 2.1.291: o claude plugin validate passa sem avisos, e o claude plugin test roda 114 testes, todos passando. O autor indica o Claude Code 2.1.274 ou mais recente. Se nada acontecer, verifique nesta ordem:

• O /compact-adviser não aparece: CLAUDE_CODE_ENABLE_FUNCTION_HOOKS não é exatamente 1, ou COMPACT_ADVISER_DISABLE está definida.
• /compact-adviser status mostra Key: missing: adicione uma chave no painel, no ambiente ou em ./.env.
• O comando funciona, mas nenhuma dica aparece: o contexto está abaixo do mínimo, ou o último turno não terminou com uma resposta fechada.
• Um toast menciona "nonessential network traffic": CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC bloqueia a requisição à TypeSafe.
• Sessões claude -p ficam sempre inativas, por design.