Cómo crear un hook en Claude Code paso a paso
Bloquea comandos peligrosos, formatea código y controla permisos con hooks deterministas en Claude Code.
- Claude Code instalado con el instalador nativo (en macOS/Linux: curl -fsSL https://claude.ai/install.sh | bash) y con la sesión iniciada
- Un repositorio Git de prueba donde puedas romper cosas sin miedo
- Python 3.9+ y jq instalados en el PATH
- Opcional: ruff o prettier para el hook de formateo
- Soltura con la terminal, JSON y scripts de shell
- Qué eventos de hook existen en Claude Code y cuándo se dispara cada uno
- Cómo leer el JSON que Claude Code envía por stdin a tu script
- Cómo bloquear una acción con exit code 2 y devolverle el motivo a Claude
- Cómo devolver JSON estructurado para pedir confirmación en lugar de bloquear
- Cómo probar y depurar hooks sin depender de que el modelo los dispare
Entender el modelo de hooks y preparar la estructura
Un hook es un comando de shell que Claude Code ejecuta de forma determinista en un punto concreto del ciclo de vida del agente. No depende de que el modelo se acuerde de algo: si el evento ocurre, el hook se ejecuta. Los eventos que más vas a usar son PreToolUse (antes de que se ejecute una herramienta, y puede bloquearla), PostToolUse (después de que termine con éxito), UserPromptSubmit (al enviar un prompt), Stop (cuando Claude termina de responder), SessionStart y Notification. Los hooks se declaran en ficheros de configuración JSON con tres niveles: ~/.claude/settings.json (todos tus proyectos), .claude/settings.json (el proyecto, se commitea y lo comparte el equipo) y .claude/settings.local.json (el proyecto, solo para ti, ignorado por Git). En este tutorial vas a trabajar a nivel de proyecto para que el equipo herede las reglas. Empieza creando una carpeta dedicada a los scripts dentro del repo, así quedan versionados junto al código que protegen.
cd ~/mi-proyecto
mkdir -p .claude/hooks
touch .claude/settings.json
# Si el fichero estaba vacío, inicialízalo con un objeto JSON válido
[ -s .claude/settings.json ] || echo '{}' > .claude/settings.jsonEscribir un hook PreToolUse que bloquee comandos peligrosos
Vamos a crear un guardián para la herramienta Bash. Claude Code envía por stdin un JSON con campos como session_id, cwd, hook_event_name, tool_name y tool_input. En el caso de Bash, tool_input.command contiene el comando exacto que Claude quiere lanzar. La regla clave de los exit codes: 0 significa todo bien y la acción continúa; 2 significa bloqueo, y lo que escribas en stderr se le devuelve a Claude como motivo para que corrija su plan; cualquier otro código es un error no bloqueante que solo verás tú. El script de abajo bloquea rm -rf, pushes directos a main o master y lecturas de ficheros .env, algo especialmente sensible si trabajas con credenciales de clientes o datos personales sujetos al RGPD en España o a las leyes de protección de datos en LATAM. Escribir el motivo en stderr de forma clara no es cosmético: Claude lo lee y suele proponer una alternativa segura en el siguiente turno.
cat > .claude/hooks/guardia_bash.py << 'EOF'
#!/usr/bin/env python3
import json
import re
import sys
try:
data = json.load(sys.stdin)
except json.JSONDecodeError:
sys.exit(0) # No bloqueamos si el input es raro
if data.get("tool_name") != "Bash":
sys.exit(0)
cmd = data.get("tool_input", {}).get("command", "")
REGLAS = [
(r"\brm\s+-[a-zA-Z]*(rf|fr)", "rm -rf no está permitido. Borra ficheros concretos o pide confirmación al usuario."),
(r"\bgit\s+push\b.*\b(main|master)\b", "Nada de push directo a main/master. Crea una rama y abre una PR."),
(r"\b(cat|less|more|head|tail)\b[^|;]*\.env\b", "No leas ficheros .env: contienen secretos."),
]
for patron, motivo in REGLAS:
if re.search(patron, cmd):
print(f"Bloqueado por hook guardia_bash: {motivo}", file=sys.stderr)
sys.exit(2)
sys.exit(0)
EOF
chmod +x .claude/hooks/guardia_bash.pyRegistrar el hook en settings.json con un matcher
Ahora conecta el script al evento. La estructura es: hooks → nombre del evento → lista de bloques, cada uno con un matcher y una lista de hooks de tipo command. El matcher filtra por nombre de herramienta y acepta expresiones regulares: Bash, Edit|Write, o mcp__.* para todas las herramientas de servidores MCP. Si lo omites o lo dejas vacío, el hook aplica a todas las herramientas del evento. Usa la variable de entorno CLAUDE_PROJECT_DIR para construir rutas absolutas: Claude Code puede cambiar de directorio durante la sesión y una ruta relativa dejaría de resolverse. El campo timeout, en segundos, evita que un script colgado bloquee la sesión. Ya de paso, deja registrado el hook PostToolUse que crearás en el paso 4, con matcher Edit|Write|MultiEdit. Las comillas escapadas alrededor de la variable protegen rutas con espacios, algo habitual en carpetas como Mis Documentos en equipos con Windows en español.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guardia_bash.py",
"timeout": 10
}
]
}
],
"PostToolUse": [
{
"matcher": "Edit|Write|MultiEdit",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/formatear.sh",
"timeout": 30
}
]
}
]
}
}Crear un hook PostToolUse que formatee cada fichero editado
El caso de uso más rentable de PostToolUse es formatear automáticamente lo que Claude acaba de escribir: dejas de pedirlo en el prompt y dejas de gastar tokens en ello. Para Edit, Write y MultiEdit, el JSON de entrada incluye tool_input.file_path con la ruta del fichero tocado. El script extrae esa ruta con jq y aplica ruff para Python o prettier para el ecosistema JavaScript. Fíjate en dos decisiones de diseño. Primero, el hook nunca devuelve exit 2: un fallo del formateador no debe interrumpir el trabajo de Claude, así que los errores se silencian con || true. Segundo, se usa npx --no-install para que no intente descargar prettier en mitad de la sesión si no está en el proyecto, lo que podría dejar el hook colgado hasta el timeout. Si en tu equipo usáis otro formateador (gofmt, rustfmt, black), añade una rama más al case.
cat > .claude/hooks/formatear.sh << 'EOF'
#!/usr/bin/env bash
set -uo pipefail
FILE=$(jq -r '.tool_input.file_path // empty')
[ -z "$FILE" ] && exit 0
[ -f "$FILE" ] || exit 0
case "$FILE" in
*.py)
command -v ruff >/dev/null && ruff format "$FILE" >/dev/null 2>&1 || true
;;
*.ts|*.tsx|*.js|*.jsx|*.json|*.css|*.md)
npx --no-install prettier --write "$FILE" >/dev/null 2>&1 || true
;;
esac
exit 0
EOF
chmod +x .claude/hooks/formatear.shDevolver JSON estructurado para pedir confirmación en vez de bloquear
Los exit codes son binarios. Cuando necesitas matices, el hook puede imprimir un JSON en stdin de salida (stdout) con exit 0 y Claude Code lo interpreta. Para PreToolUse, el objeto hookSpecificOutput admite permissionDecision con valores allow (aprueba sin preguntar), deny (bloquea y explica a Claude el motivo) o ask (fuerza el diálogo de confirmación al usuario). Esto es perfecto para ficheros delicados que sí se pueden tocar, pero no sin que un humano lo vea: migraciones de base de datos, workflows de CI o configuración de infraestructura. Crea este segundo hook y añádelo al bloque PreToolUse con un matcher Edit|Write|MultiEdit, igual que hiciste en el paso 3. Puedes tener varios bloques para el mismo evento; Claude Code ejecuta en paralelo todos los hooks cuyo matcher coincida.
cat > .claude/hooks/ficheros_sensibles.py << 'EOF'
#!/usr/bin/env python3
import json
import sys
data = json.load(sys.stdin)
ruta = data.get("tool_input", {}).get("file_path", "")
SENSIBLES = ("migrations/", ".github/workflows/", "terraform/", "docker-compose")
if any(s in ruta for s in SENSIBLES):
print(json.dumps({
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "ask",
"permissionDecisionReason": f"{ruta} es un fichero sensible: revisa el cambio antes de aceptarlo."
}
}))
sys.exit(0)
EOF
chmod +x .claude/hooks/ficheros_sensibles.pyProbar y depurar los hooks antes de confiar en ellos
No esperes a que Claude decida lanzar un rm -rf para saber si tu guardián funciona. Como los hooks son simples scripts que leen JSON por stdin, puedes simular la entrada desde la terminal y comprobar el exit code. Después, valida dentro de Claude Code: arranca con claude --debug para ver en la salida qué hooks se ejecutan, con qué comando y qué devuelven. Una prueba end-to-end rápida es pedirle a Claude algo como borra la carpeta build con rm -rf y comprobar que se bloquea, que te muestra el motivo y que propone una alternativa. Finalmente, commitea la carpeta .claude/hooks y el settings.json: cualquier compañero que clone el repo tendrá las mismas protecciones. Recuerda que los hooks se ejecutan con tus permisos de usuario, así que revisa los scripts de proyectos ajenos antes de abrirlos con Claude Code.
# 1. Debe bloquear (exit 2) y mostrar el motivo por stderr
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf ./build"}}' \
| python3 .claude/hooks/guardia_bash.py; echo "exit: $?"
# 2. Debe permitir (exit 0)
echo '{"tool_name":"Bash","tool_input":{"command":"ls -la"}}' \
| python3 .claude/hooks/guardia_bash.py; echo "exit: $?"
# 3. Debe devolver JSON con permissionDecision ask
echo '{"tool_input":{"file_path":"db/migrations/001_init.sql"}}' \
| python3 .claude/hooks/ficheros_sensibles.py
# 4. Validar la configuración y arrancar en modo debug
jq . .claude/settings.json > /dev/null && echo 'settings.json OK'
claude --debugHas montado un sistema de hooks de nivel de producción en Claude Code: un guardián PreToolUse que bloquea comandos destructivos y le explica a Claude por qué, un formateador PostToolUse que deja cada fichero limpio sin gastar un solo token, y un hook con salida JSON que exige confirmación humana sobre ficheros críticos. Además sabes probarlos de forma aislada y depurarlos con claude --debug, y los has versionado para que todo tu equipo herede las mismas reglas. Si quieres ir más allá y convertir esto en un flujo de trabajo completo con subagentes, comandos personalizados y CLAUDE.md, te conviene profundizar en el desarrollo asistido por IA con Claude Code de forma estructurada.