🌱 Empieza aquí · Python confiable en tus scripts

Esta semilla es una pieza de plomería para quien escribe sus propios scripts o hooks (ganchos de automatización) en shell. Resuelve un dolor puntual pero muy molesto: que tus scripts inviten a Python y, en Windows, les responda un impostor en lugar del Python de verdad.

El porqué, en una frase

En Windows, la Microsoft Store deja un "señuelo": los nombres python y python3 apuntan a un programa falso que, en vez de correr tu código, te pide instalar Python desde la tienda y falla. Tus scripts se rompen aunque tengas Python bien instalado. Esta semilla encuentra el Python real y te lo deja listo para usar.

Para instalarla

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

"Siembra esta semilla 🌱"

Con eso basta. Tu asistente coloca el archivo en su lugar y te dice cómo comprobar que quedó. Vas a ver algo de texto técnico en inglés; ni caso, él te guía.

¿Otras formas de pedírselo? "instala este helper de Python", "pon a funcionar el detector de Python", "haz el setup de esto". Te entiende igual.

Para el asistente que siembra 🤖

Estás instalando un helper sourceable (una utilidad que otros scripts "importan" con source, no un programa que se ejecuta solo). NO es un hook registrado: no lleva entrada en settings.json ni se dispara con ningún evento. Su trabajo es dejar disponibles la variable $PY_CMD y la función py_run para que TUS otros scripts/hooks las usen. Sigue estos pasos.

1. Copia el archivo a la carpeta de hooks

Elige una ubicación:

• Recomendado — global (disponible para todos tus scripts): cópialo a la carpeta de configuración del asistente, dentro de hooks/. En Claude Code y Cowork suele ser ~/.claude/hooks/.
• Alternativa — por proyecto (solo este repositorio): cópialo a <TU-PROYECTO>/.claude/hooks/.

Global (Claude Code / Cowork · macOS, Linux, o Windows con Git Bash):

mkdir -p "$HOME/.claude/hooks"
cp kernel/python-helper.sh "$HOME/.claude/hooks/python-helper.sh"

No necesita chmod +x: como se usa con source (se lee, no se ejecuta como programa), le basta con tener permiso de lectura, que ya trae de fábrica.

2. Úsalo desde tus propios scripts

En cualquier script o hook .sh donde quieras invocar Python, agrega al inicio:

source "$HOME/.claude/hooks/python-helper.sh"

Y a partir de ahí, en lugar de escribir python3 (que en Windows puede ser el impostor), usa la función py_run o la variable $PY_CMD:

# Con la función (recomendado · se salta en silencio si no hay Python):
ruta=$(printf '%s' "$entrada" | py_run -c "import sys, json; print('ok')")

# O directo con la variable:
ruta=$(printf '%s' "$entrada" | "$PY_CMD" -c "print('ok')")

Si la máquina no tiene ningún Python real, $PY_CMD queda vacío y py_run no hace nada (devuelve código 1). Así tu script sigue siendo no-bloqueante: trata el resultado vacío como "no pasa nada" y continúa.

3. Verificación post-siembra (obligatoria)

a) El archivo quedó colocado:

ls -l "$HOME/.claude/hooks/python-helper.sh"; echo "exit=$?"

Salida esperada: una línea que lista el archivo y exit=0. Si sale No such file or directory, la copia no se hizo; repite el paso 1.

b) Detecta el Python real (prueba de comportamiento):

source "$HOME/.claude/hooks/python-helper.sh"
echo "PY_CMD=[$PY_CMD]"
py_run -c "print('python vivo:', __import__('sys').version.split()[0])"; echo "exit=$?"

Salida esperada (máquina con Python): PY_CMD=[python3] (o py / python, según el sistema), luego una línea python vivo: 3.x.y y exit=0. En una máquina sin Python: PY_CMD=[] y py_run termina con exit=1 sin imprimir nada — ese es el comportamiento correcto (silent-skip), no un error.

Cuando ambas partes pasen, avísale a la persona en una línea qué gana con esto.

Placeholders que debes reemplazar por valores reales:

| Placeholder | Qué es | |---|---| | <TU-PROYECTO> | La carpeta raíz del proyecto/repositorio del usuario. |

✅ ¿Cómo sé que funcionó?

De ahora en adelante, cualquier script o hook tuyo que llame a Python usando este helper va a encontrar el Python de verdad, sin importar si estás en Windows, macOS o Linux. Se acabaron los fallos raros de "no se encontró Python" cuando sí lo tienes instalado.

Y si algún día trabajas en una máquina sin Python, tus scripts no se rompen: simplemente se saltan esa parte en silencio y siguen su camino. Es una plomería que trabaja calladita por ti. 🫡