🌱 Empieza aquí · Hook envoltorio: shell delgado que delega en Python

Esta semilla es una pieza de plomería para quien arma sus propios ganchos de arranque (hooks). Resuelve un dolor concreto: cuando la lógica de arranque se hace en puro shell y se vuelve lenta, tu asistente tarda segundos de más en abrir cada sesión. La solución es dejar el trabajo pesado en Python (que corre en milisegundos) y usar este envoltorio de shell delgado como la puerta de entrada que tu asistente sabe invocar.

El porqué, en una frase

Un hook de arranque tiene que ser de shell (es lo que el asistente sabe llamar), pero el shell puro es lento para tareas grandes. Este envoltorio no hace el trabajo: lo delega a un script de Python vecino, con red de seguridad para que jamás rompa el arranque, en Windows, macOS o Linux.

Para instalarla

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

"Siembra esta semilla 🌱"

Con eso basta de tu parte. Tu asistente hace todo lo técnico y al final te dice cómo comprobar que quedó funcionando. Vas a ver algo de texto técnico en inglés; ni caso, él te guía.

¿Otras formas de pedírselo? "instala este envoltorio", "pon a funcionar el hook que delega en Python", "haz el setup de esto". Te entiende igual.

Para el asistente que siembra 🤖

Estás instalando una plantilla de hook envoltorio: un gancho de shell delgado que delega el trabajo real a un script de Python vecino, con fallback de intérprete (python → python3) y salida siempre exitosa (no bloqueante). Es un hook registrado: sí lleva chmod +x y sí lleva una entrada en settings.json. Sigue estos pasos y no inventes rutas: usa $HOME siempre.

Importante: esta semilla es el ENVOLTORIO, no el trabajo. Por sí sola no hace nada útil: existe para envolver TU script de Python (el que de verdad calcula o inyecta algo al arranque). Para que veas la tubería funcionar de inmediato, la semilla trae un ejemplo mínimo listo para sembrar: kernel/mi-trabajo.ejemplo.py (solo imprime un saludo con la fecha). Siémbralo primero para comprobar que todo enchufa, y luego reemplázalo por el .py real del usuario. Si aún no tiene el suyo, avísale que ese ejemplo es el punto de partida.

1. Copia el envoltorio a la carpeta de hooks y dale permiso de ejecución

Renómbralo a algo que describa su función (aquí usamos mi-hook.sh de ejemplo):

Claude Code / Cowork (macOS o Linux):

mkdir -p "$HOME/.claude/hooks"
cp kernel/hook-envoltorio-python.sh "$HOME/.claude/hooks/mi-hook.sh"
chmod +x "$HOME/.claude/hooks/mi-hook.sh"

Windows (Git Bash / WSL): misma ruta ~/.claude/hooks/. El envoltorio usa bash, que viene con Git Bash o WSL. Si el usuario corre Claude Code nativo en Windows sin bash, avísale que este hook necesita un entorno con bash disponible.

2. Coloca (o apunta a) el script de Python que hace el trabajo

Lo más simple: pon el .py junto al envoltorio con el nombre que el envoltorio espera. Por defecto busca mi-trabajo.py en su misma carpeta.

Para probar YA que todo enchufa, siembra el ejemplo incluido con ese mismo nombre:

cp kernel/mi-trabajo.ejemplo.py "$HOME/.claude/hooks/mi-trabajo.py"

Cuando confirmes que la tubería funciona (paso 5), reemplaza ese archivo por el script real del usuario:

cp <TU-SCRIPT>.py "$HOME/.claude/hooks/mi-trabajo.py"

Si tu .py tiene otro nombre o vive en otra carpeta, edita la marca «AJUSTA» (2) del envoltorio y cambia la línea PY_SCRIPT=... por la ruta real. (También puedes apuntarlo temporalmente exportando HOOK_PY_SCRIPT, útil para probar.)

3. Registra el hook en settings.json

Abre $HOME/.claude/settings.json (créalo si no existe) y agrega esta entrada. El ejemplo usa el evento SessionStart (arranque de sesión), que es el caso típico de un inyector de contexto; si tu .py sirve para otro momento, usa el evento que corresponda. Si ya hay hooks de ese evento, suma este objeto al arreglo existente en lugar de reemplazarlo:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash $HOME/.claude/hooks/mi-hook.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Si el .py imprime texto en su salida estándar (print), en un hook de SessionStart ese texto se le inyecta al asistente como contexto de arranque. Ese suele ser justo el propósito del patrón.

4. (Opcional) Silenciar el hook en ciertos entornos

El envoltorio trae una puerta de salida: si defines la variable de entorno HOOK_ENVOLTORIO_SKIP, el hook se salta por completo. Útil para apagarlo en procesos automatizados o forks donde no lo quieres. Renómbrala o bórrala si no la necesitas (marca «AJUSTA» (1) en el envoltorio).

5. Verificación post-siembra (obligatoria)

a) Los archivos quedaron colocados:

ls -l "$HOME/.claude/hooks/mi-hook.sh" "$HOME/.claude/hooks/mi-trabajo.py"; echo "exit=$?"

Salida esperada: dos líneas listando los archivos y exit=0. Si sale No such file or directory, faltó copiar algo; repite el paso 1 o 2.

b) El envoltorio corre el Python y pasa su salida (prueba de comportamiento). Crea un .py de prueba y córrelo a través del envoltorio:

printf 'print("hook vivo desde Python")\n' > /tmp/mi-trabajo-prueba.py
HOOK_PY_SCRIPT=/tmp/mi-trabajo-prueba.py bash "$HOME/.claude/hooks/mi-hook.sh"; echo "exit=$?"

Salida esperada: la línea hook vivo desde Python seguida de exit=0. Eso confirma que el envoltorio encontró Python, corrió el script y dejó pasar su salida.

c) Es NO BLOQUEANTE (prueba de la red de seguridad). Apúntalo a un .py que no existe: debe terminar en exit=0 sin romper nada:

HOOK_PY_SCRIPT=/tmp/no-existe.py bash "$HOME/.claude/hooks/mi-hook.sh"; echo "exit=$?"
rm -f /tmp/mi-trabajo-prueba.py

Salida esperada: sin errores visibles y exit=0. Ese es el diseño: si Python falla o no está, el arranque sigue su curso.

d) Quedó registrado en settings.json:

grep -q 'mi-hook.sh' "$HOME/.claude/settings.json" && echo 'REGISTRADO'

Salida esperada: REGISTRADO.

Cuando las cuatro pruebas den lo esperado, avísale a la persona en una línea qué gana con esto.

Placeholders que debes reemplazar por valores reales:

| Placeholder | Qué es | |---|---| | <TU-SCRIPT>.py | El script de Python del usuario que hace el trabajo real del hook. | | mi-hook.sh / mi-trabajo.py | Nombres de ejemplo; ponles los que describan tu caso. |

✅ ¿Cómo sé que funcionó?

De ahora en adelante, cuando abras una sesión de trabajo, tu hook de arranque hará su tarea rápido —porque el trabajo pesado corre en Python, no en shell lento— y sin arriesgarse a trabar la sesión. Si algún día trabajas en una máquina donde Python no está disponible, el arranque no se rompe: el hook simplemente se salta esa parte en silencio y sigue su camino.

Es una plomería que trabaja calladita por ti: veloz cuando puede, invisible cuando no, y nunca un estorbo. 🫡