Compact Adviser: sabe cuándo usar /compact en Claude Code

Compact Adviser responde a una pregunta: ¿debería ejecutar /compact ahora? Lo ha escrito Kun Chen (kunchenguid) y se publica para Claude Code, Pi, Codex CLI y Grok desde un mismo repositorio. Esta página trata del mod para Claude Code que está en packages/claude-mod.

Compactar demasiado pronto tira contexto que todavía necesitas; compactar demasiado tarde hace que cada turno arrastre un historial largo. Después de cada turno terminado, el mod comprueba unas cuantas condiciones locales baratas y, si se cumplen, hace al modelo Jev de TypeSafe dos preguntas breves sobre la conversación: ¿está terminada la última unidad de trabajo del asistente?, ¿hizo el asistente el trabajo él mismo o se limitó sobre todo a coordinar? Las dos respuestas se combinan en una puntuación. Si la puntuación supera un umbral, aparece una línea de estado: "work appears completed or recorded. Run /compact to save tokens."

El umbral es estricto (0,90) mientras el contexto está casi vacío y se relaja hacia 0,50 a medida que el contexto se acerca al punto de autocompactación de Claude Code, porque un aviso equivocado sale más caro cuando todavía queda espacio. Si eliges el modo automático, el mod ejecuta él mismo la compactación en ese punto de control en lugar de limitarse a avisar.

Necesita una clave de API de TypeSafe, que aportas tú.

Un aviso real necesita más de 40.000 tokens de contexto y una clave de TypeSafe, algo que no cabe en un clip corto. La grabación inicia Claude Code con el mod cargado, ejecuta /compact-adviser status (modo, mínimo, presupuesto y estado de la clave), luego abre el panel de configuración de /compact-adviser y baja hasta la fila de la clave de API de TypeSafe, que muestra missing.

Usa cualquiera de los métodos del bloque de instalación; ambos instalan directamente desde el marketplace del autor. El mod no hace absolutamente nada a menos que Claude Code arranque con CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1, así que inícialo con esa variable y después ejecuta /compact-adviser para añadir tu clave de TypeSafe.

Todo empieza en el hook de turn.complete de 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;
});

Solo cuenta un turno del bucle principal que terminó con una respuesta real; los turnos de subagentes y los abortados se omiten. settle cuenta el intercambio y aplica los filtros baratos: modo distinto de off, una clave presente, contexto igual o superior a minContextTokens y ningún periodo de espera ni aplazamiento. Si se cumplen, programa judgeCheckpoint con $.clock.after(0, …) para no retrasar el turno.

judgeCheckpoint construye una instantánea acotada a partir de $.session.messages() (consulta lib/snapshot.ts), omite la petición si la conversación tiene menos de 20.000 tokens o si ese mismo punto de control ya se evaluó, y la envía a https://api.typesafe.ai/v1/systemone con $.http.fetch. La petición caduca a los 2 segundos, y un error, un tiempo agotado o una respuesta mal formada nunca cuentan como un sí: el mod espera más antes de reintentar y muestra un toast. Cuando la puntuación es suficiente, el modo de aviso llama a $.ui.status con el aviso, y el modo automático llama a $.session.compact con instrucciones para conservar con exactitud el trabajo actual, las tareas pendientes y el siguiente paso.

Cualquier compactación, tuya o de Claude Code, reinicia el periodo de espera de la sesión a través del hook de session.compact.

Ejecuta /compact-adviser para abrir el panel de configuración, o usa sus subcomandos: auto, hint y off cambian el modo; threshold 60000 fija el contexto mínimo; budget 450000 fija un presupuesto de contexto contra el que se mide el umbral en lugar del punto de autocompactación; snooze omite los tres siguientes intercambios; dismiss borra el aviso actual; status imprime el estado actual. El modo, el mínimo, el presupuesto y el registro de peticiones también son filas de /config. Un perfil de evaluación (JSON en el ajuste profile) puede cambiar las preguntas, el peso de la puntuación o el calendario del umbral.

Leímos register.ts, todos los archivos de lib/, plugin.json, hooks.json, package.json y los helpers de los tests antes de ejecutar nada.

• Red: el mod envía una petición por cada punto de control que cumple los requisitos a https://api.typesafe.ai/v1/systemone, un servicio de terceros, con tu clave en la cabecera Authorization. El cuerpo es una instantánea de la conversación reciente, con un máximo de 32.000 bytes, tras ocultar en lo posible los patrones de claves y los archivos .env, auth.json, id_rsa/id_ed25519, .pem y .key. TYPESAFE_BASE puede apuntarlo a otra base https, o a una http de loopback. Instalar el plugin se considera consentimiento para enviar esto cuando hay una clave disponible, así que pon el modo en off para el trabajo que no deba salir de tu máquina.
• Archivos: lee .env en la carpeta de la sesión para buscar TYPESAFE_API_KEY. Solo escribe cuando activas el registro de peticiones: ~/.claude/compact-adviser-requests-<session-id>.jsonl, que nunca contiene la clave.
• Configuración: guardar desde el panel escribe las filas de userConfig propias del plugin mediante $.config.set. La clave guardada no se muestra en /config.
• Compactación: solo en modo automático, tras un diálogo de confirmación que aparece una sola vez.

No hay scripts de instalación, ni código empaquetado o minificado, ni telemetría más allá de la propia petición a TypeSafe.

Validado con Claude Code 2.1.291: claude plugin validate pasa sin avisos y claude plugin test ejecuta 114 tests, todos correctos. El autor indica Claude Code 2.1.274 o posterior. Si no pasa nada, comprueba lo siguiente en este orden:

• Falta /compact-adviser: CLAUDE_CODE_ENABLE_FUNCTION_HOOKS no vale exactamente 1, o COMPACT_ADVISER_DISABLE está definida.
• /compact-adviser status dice Key: missing: añade una clave en el panel, en el entorno o en ./.env.
• El comando funciona pero no aparece ningún aviso: el contexto está por debajo del mínimo, o el último turno no terminó con una respuesta cerrada.
• Un toast menciona "nonessential network traffic": CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC bloquea la petición a TypeSafe.
• Las sesiones de claude -p siempre están inactivas por diseño.