ctx-handoff: domina las sesiones largas de Claude Code

ctx-handoff es un mod de la comunidad creado por CabLate (cablate) para las sesiones largas de Claude Code, es decir, conversaciones que duran horas. Reúne varias tareas que aparecen en ellas: mientras no estás, envía una petición diminuta para que la caché del prompt no caduque; convierte tus instrucciones repetidas en notas por proyecto que se cargan en las conversaciones nuevas; y avisa a Claude cuando reintenta una herramienta que falla o dice «hecho» sin haber comprobado nada.

Otras dos funciones más grandes son menos automáticas. Un traspaso opcional escribe un resumen del trabajo, limpia la conversación y continúa en una nueva cuando el contexto llega a un umbral; viene desactivado. Las guardas son comprobaciones de llamadas a herramientas que el mod redacta a partir de reglas que repites, y solo se aplican cuando las apruebas. Un panel sobre el prompt (/handoff panel) muestra guardas, recuerdos, reglas, la última actualización de notas y todos los ajustes.

El README del autor está pensado para suscripciones de Claude y sesiones largas con contexto grande. Con clave de API, Bedrock o Vertex la caché dura solo cinco minutos, así que el autor sugiere /handoff refresh off.

La grabación inicia Claude Code con el mod cargado en el pequeño proyecto de demostración. El pie muestra enseguida ctx-handoff: 30 more messages until notes update, la cuenta atrás hasta la próxima actualización de notas en segundo plano. Después ejecuta /handoff guard, que imprime Guards: none con las condiciones en las que se redactan guardas, y /handoff refresh, que imprime Currently on. Usage: /handoff refresh on|off. El clip no hace ninguna petición al modelo y no abre el panel, porque este muestra la ruta completa del archivo de notas.

Usa cualquiera de los métodos del bloque de instalación; instalan directamente desde el marketplace del propio autor. Inicia una sesión nueva y ejecuta /handoff. La cuenta atrás del pie aparece cuando empieza la sesión.

Todo se registra desde un único módulo, hooks/register.ts. Cada turno terminado reinicia un temporizador de inactividad. Cuando salta y el contexto supera min_tokens, el mod envía una petición fork mínima para leer la conversación en caché y programa la siguiente. Esta es la función de programación, de hooks/register.ts:

async function schedule($: EngineInterface, delay = cfg.idleMs) {
  rt.idle?.cancel()
  if (await awayPaused($)) { rt.idle = undefined; await update($, idleState, () => null); return }
  rt.idle = $.clock.after(delay, () => void onIdle($))
  const due = (await $.clock.now()) + delay
  await update($, idleState, () => ({ due, refreshes: rt.refreshes }))
}

Por defecto la inactividad es de 50 minutos y hay como máximo 3 refrescos; después se guarda un traspaso por ausencia sin limpiar. Cada 30 mensajes del usuario, o antes de un traspaso, una petición aparte sin historial envía solo la parte nueva de la conversación a un modelo de notas (claude-sonnet-5-5, poco esfuerzo). Sus acciones en JSON se validan en código, las citas del usuario deben aparecer en tus mensajes reales y las líneas que parecen secretos se descartan antes de escribir nada. Las notas se inyectan en las conversaciones nuevas mediante prompt.context.

El mod no declara userConfig. Los ajustes están en la pestaña de ajustes del panel (/handoff panel y luego la tecla 5), y el mod también lee pluginConfigs["ctx-handoff@<marketplace>"].options de settings.json; el valor del panel tiene prioridad. Incluyen auto_handoff (desactivado por defecto), threshold (600000 tokens), idle_minutes (50), max_refresh (3), min_tokens (30000), distill_every (30), notes_model, retry_nudge, done_check, reply_language y language. Los comandos con barra cubren el resto: /handoff now, dry, distill on|off, refresh on|off, away pause|resume, guard, resume, continue y resend.

Leímos el manifiesto, hooks/hooks.json, hooks/register.ts completo y los módulos de ajustes, notas, traspaso, guardas, bucles, idioma, promoción y el prompt de destilado. El resto de archivos, sobre todo las cadenas i18n, la vista del panel y pequeños ayudantes de registros, los revisamos con búsquedas para detectar efectos secundarios, sin leerlos línea por línea. El repositorio no tiene package.json, script de instalación, binarios ni código minificado. tools/ contiene scripts del autor que el plugin no carga y que no ejecutamos. No hay caracteres Unicode ocultos.

Lo que conviene saber:

• Peticiones al modelo, ninguna otra red. No hay fetch, llamadas a procesos ni código de red. El mod llama a $.model.fork y $.model.complete, que usan tu cuota de Claude. El texto de la conversación se envía para las notas y los resúmenes de traspaso, igual que la propia conversación.
• Escribe fuera de su propio almacén. $.fs.write crea y actualiza <carpeta de configuración de claude>/projects/<espacio de trabajo>/memory/ctx-handoff.md, y escribe una copia en .ctx-handoff-backup/ antes de borrar una nota desde el panel. Las actualizaciones de notas en segundo plano están activadas por defecto, pero se omiten si la sesión empieza en tu carpeta personal. No toca settings.json, archivos de shell ni LaunchAgents, y lee HOME, USERPROFILE y CLAUDE_CONFIG_DIR.
• Inyecta texto en el modelo. prompt.context añade a las conversaciones nuevas tus notas, una nota de progreso opcional y preguntas sobre guardas, marcadas con [ctx-handoff]. Los resultados de herramientas pueden llevar avisos. Cuando una regla se repite 3 veces en un repositorio git, el texto inyectado le dice a Claude que la escriba en el repositorio (CLAUDE.md, .claude/skills, hooks) sin preguntar, pero sin hacer commit. Las notas son resúmenes de tus conversaciones escritos por el modelo, así que revisa el archivo de vez en cuando.
• Hooks que condicionan. tool.call solo puede denegar una llamada por una guarda que hayas aprobado. classic.Stop puede bloquear una respuesta de «hecho» por turno cuando se editaron archivos y no se ejecutó ninguna comprobación (done_check, activado por defecto). prompt.submit retiene tus mensajes mientras corre un traspaso. Si activas el traspaso automático, el mod ejecuta /clear y envía el resumen él mismo.
• Sin demonio ni telemetría. Los temporizadores viven solo en el proceso de Claude Code. Las estadísticas de uso se quedan en el almacén del plugin.
• Entornos gestionados. Según claude plugin validate, los hooks prompt.context y classic.Stop no se ejecutan en un plugin instalado por el usuario cuando una organización gestiona Claude Code.
• Licencia. MIT, con archivo LICENSE.

claude plugin validate no informó de errores. Su única advertencia es que el CLAUDE.md de la raíz del repositorio no se carga como contexto del plugin. Los 290 tests del autor, en 15 archivos, pasaron con Claude Code 2.1.303.

Probado con Claude Code 2.1.303 en macOS (validate, tests y la grabación). El README del autor pide 2.1.287 o posterior. Si /handoff no hace nada:

• claude --version es 2.1.287 o posterior y iniciaste una sesión nueva tras instalar.
• Puede que ya exista otro comando /handoff; en ese caso el mod registra /ctx-handoff.
• La cuenta atrás del pie no aparece si las actualizaciones de notas están desactivadas o si iniciaste Claude Code en tu carpeta personal.
• Los refrescos de caché solo ayudan donde la caché dura una hora, así que con clave de API desactívalos con /handoff refresh off.
• Ejecuta /handoff para ver el estado actual, incluido el último fallo y la ruta del archivo de notas.