🌱 Empieza aquí · Aviso de caché de contexto expirada

¿Qué es esto y por qué te sirve?

Cuando platicas con tu asistente, él guarda una copia temporal de tu conversación —se llama caché de contexto— para no tener que releer todo desde cero en cada respuesta. Eso te ahorra tiempo y costo. Pero esa copia tiene fecha de caducidad: si te distraes y dejas la conversación en pausa un buen rato, la copia se vence. Cuando eso pasa, el siguiente mensaje que mandes obliga al asistente a reprocesar TODO el contexto de nuevo, y eso te sale caro (en tokens o en tu plan).

Esta semilla instala un pequeño vigilante que te avisa justo antes de que eso pase. Si estuviste inactivo más tiempo del que dura la caché, detiene tu mensaje una sola vez y te dice: "oye, la caché ya venció; compacta la conversación primero para que salga más barato, o vuelve a mandar tu mensaje si prefieres seguir así". También te avisa cuando retomas una sesión que habías guardado (ahí la caché casi siempre ya expiró).

En corto: te ahorra dinero avisándote antes de que pagues de más por revivir un contexto viejo.

Para instalarla (una sola vez)

Abre esta carpeta con Claude Code o Cowork y dile a tu asistente:

"Siembra esta semilla 🌱"

Y ya. Tu asistente hace todo lo técnico por ti. Vas a ver comandos raros en la pantalla; ni caso, él se encarga. Cuando termine, te dice cómo comprobar que quedó.

Otras formas de pedirlo que también entiende: "instala esta semilla", "configura el aviso de caché expirada", "pon esto a funcionar".

Para el asistente que siembra 🤖

Eres el asistente. Esto es un sistema de tres hooks (ganchos de automatización) en Python que trabajan en equipo. El protagonista es el aviso, pero necesita a sus dos compañeros para tener contra qué comparar:

kernel/cache-warn-stop.py — se cablea al evento Stop (cuando terminas de responder). Anota la hora de tu última respuesta. Es el que crea la "línea base".
kernel/cache-expiry-warn.py — se cablea al evento UserPromptSubmit (justo antes de mandar el mensaje del usuario). Compara contra la línea base y, si la pausa superó el TTL de la caché, bloquea una vez con el aviso.
kernel/cache-resume-detect.py — se cablea al evento SessionStart (al abrir o retomar sesión). Si la sesión se retomó, arma un aviso de costo para el primer mensaje.

Los tres necesitan python3 instalado (viene por defecto en macOS y Linux; en Windows verifica con python3 --version o usa Git Bash / WSL).

0. Placeholders según la plataforma

Sustituye estos placeholders por la ruta real de la plataforma del usuario:

| Placeholder | Claude Code (global) | Claude Code (un solo proyecto) | Cowork (escritorio) | |---|---|---|---| | <TU-RUTA-HOOKS> | ~/.claude/hooks/ | .claude/hooks/ (dentro del proyecto) | ~/.claude/hooks/ | | <TU-SETTINGS> | ~/.claude/settings.json | .claude/settings.json | ~/.claude/settings.json |

Recomendación por defecto: instalación global en ~/.claude/, para que el aviso funcione en todas las carpetas del usuario. Cowork de escritorio comparte la misma configuración ~/.claude/.

1. Copiar los tres scripts a la carpeta de hooks

mkdir -p <TU-RUTA-HOOKS>
cp kernel/cache-warn-stop.py kernel/cache-expiry-warn.py kernel/cache-resume-detect.py <TU-RUTA-HOOKS>

2. Darles permiso de ejecución (chmod)

chmod +x <TU-RUTA-HOOKS>/cache-warn-stop.py \
         <TU-RUTA-HOOKS>/cache-expiry-warn.py \
         <TU-RUTA-HOOKS>/cache-resume-detect.py

3. Cablearlos en settings.json

Edita <TU-SETTINGS> y agrega este bloque. Si el archivo ya tiene secciones Stop, UserPromptSubmit o SessionStart, NO las reemplaces: agrega el objeto del comando dentro del array hooks que ya exista (fusiona, no sobrescribas).

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "python3 <TU-RUTA-HOOKS>/cache-warn-stop.py", "timeout": 5 }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "python3 <TU-RUTA-HOOKS>/cache-expiry-warn.py", "timeout": 5 }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "python3 <TU-RUTA-HOOKS>/cache-resume-detect.py", "timeout": 5 }
        ]
      }
    ]
  }
}

Sustituye <TU-RUTA-HOOKS> por la ruta real del paso 0. Si tu plataforma no resuelve el ~, usa la ruta absoluta (por ejemplo /Users/tu-usuario/.claude/hooks/).

4. Ajustar el tiempo de expiración al plan del usuario (importante)

Distintos planes usan distintas duraciones de caché. El default del hook es 60 minutos. Si el plan del usuario usa otra duración (por ejemplo 5 minutos), ajusta la variable de entorno CACHE_TTL_MINUTES. Agrega un bloque env en <TU-SETTINGS>:

{
  "env": {
    "CACHE_TTL_MINUTES": "5"
  }
}

Si no sabes la duración exacta, deja el default de 60. Es un aviso, no un candado: equivocarle solo hace que avise un poco antes o un poco después.

5. VERIFICACIÓN post-siembra (hazla y muestra el resultado)

# 1) Los tres scripts existen y son ejecutables
ls -l <TU-RUTA-HOOKS>/cache-warn-stop.py \
      <TU-RUTA-HOOKS>/cache-expiry-warn.py \
      <TU-RUTA-HOOKS>/cache-resume-detect.py

# 2) El Stop hook crea la línea base
echo '{"session_id":"prueba-siembra"}' | python3 <TU-RUTA-HOOKS>/cache-warn-stop.py
cat ~/.cache/cache-expiry-warn/prueba-siembra.json

# 3) Con caché aún fresca, el aviso deja pasar el mensaje
echo '{"session_id":"prueba-siembra","prompt":"hola"}' | python3 <TU-RUTA-HOOKS>/cache-expiry-warn.py

# 4) Forzando expiración (TTL=0 min), el aviso bloquea una vez
echo '{"session_id":"prueba-siembra","prompt":"hola"}' | \
  CACHE_TTL_MINUTES=0 python3 <TU-RUTA-HOOKS>/cache-expiry-warn.py

# 5) La segunda vez en la misma pausa ya deja pasar (avisa una sola vez)
echo '{"session_id":"prueba-siembra","prompt":"hola"}' | \
  CACHE_TTL_MINUTES=0 python3 <TU-RUTA-HOOKS>/cache-expiry-warn.py

# 6) Limpieza de la prueba
rm -f ~/.cache/cache-expiry-warn/prueba-siembra.json

Salida esperada:

Paso 1: aparecen las tres rutas con permisos -rwxr-xr-x (la x = ejecutable).
Paso 2: imprime un JSON con last_stop_time (la hora anotada).
Paso 3: imprime {"continue": true} (deja pasar, la caché sigue fresca).
Paso 4: imprime {"decision": "block", "reason": "Cache warning: ..."} (avisa).
Paso 5: imprime {"continue": true} (ya avisó de esta pausa, no repite).
Paso 6: sin salida (solo borra el archivo de prueba).

Si los pasos 2 a 5 dan eso, la semilla quedó sembrada y funcionando.

Troubleshooting

"python3: command not found" → el usuario no tiene Python 3. Que lo instale (macOS: brew install python3; Linux: gestor de paquetes; Windows: python.org o WSL).
El aviso nunca aparece → revisa que el Stop hook esté cableado: sin él no hay línea base y cache-expiry-warn.py siempre deja pasar. Verifica el paso 2.
Avisa demasiado seguido / demasiado tarde → ajusta CACHE_TTL_MINUTES (paso 4) a la duración real de la caché del plan del usuario.
Nada rompe si falla → los hooks están hechos para que, ante cualquier error, dejen pasar el mensaje. Nunca bloquean de forma permanente.

✅ ¿Cómo sé que funcionó?

En el día a día, si dejas una conversación en pausa más tiempo del que dura la caché y luego escribes, el asistente te va a detener una vez con un aviso corto: "la caché ya venció; compacta primero para que salga más barato, o vuelve a mandar tu mensaje para seguir". Tú decides. Si retomas antes de que expire, no te molesta. Y al abrir una sesión guardada, te avisa que ese primer turno reconstruye el contexto.

Es un guardián de tu bolsillo: te avisa antes de que pagues de más por revivir un contexto viejo. 🌱