Directorio / Guías / Claude Code
Hooks en Claude Code: reglas que se cumplen siempre
Cómo hacer que algo pase cada vez sin depender de que Claude se acuerde: formatear lo que edita, bloquear un archivo sensible y qué revisar por seguridad.
Un hook es un comando que Claude Code ejecuta solo, en un momento fijo: antes de usar una herramienta, después de editar un archivo o al terminar de responder. La diferencia con escribir una regla en el CLAUDE.md es la garantía. Claude sigue el CLAUDE.md casi siempre. Un hook corre siempre.
En mejora de procesos esto se llama poka-yoke: en vez de pedirle a alguien que se acuerde, diseñas el paso para que el error no pueda ocurrir.
Las tres piezas
- El evento: en qué momento corre.
- El matcher: a qué herramientas aplica.
Edit|Writesignifica editar o escribir archivos. Distingue mayúsculas de minúsculas. - El comando: lo que se ejecuta. Recibe los datos de la acción en formato JSON, por ejemplo la ruta del archivo que Claude quiere editar.
| Evento | Cuándo corre |
|---|---|
PreToolUse | Antes de que Claude use una herramienta. Puede bloquearla. |
PostToolUse | Después de que la herramienta terminó bien. |
Notification | Cuando Claude Code te necesita, por ejemplo para aprobar algo. |
Stop | Cuando Claude termina de responder. |
SessionStart | Al empezar o retomar una sesión. |
Dónde se configuran
| Archivo | Alcance |
|---|---|
~/.claude/settings.json | Todos tus proyectos |
.claude/settings.json | Este proyecto. Se puede compartir por git. |
.claude/settings.local.json | Este proyecto, solo en tu computadora |
Todo va dentro de una sola clave "hooks". Si el archivo ya tiene una, agrega el evento nuevo adentro en lugar de crear otra. También puedes describirle a Claude el hook que quieres y pedirle que lo escriba; igual revisa lo que escribió.
Ejemplo 1: formatear cada archivo que Claude edita
Si tu proyecto usa Prettier, este hook lo corre después de cada edición y el formato queda parejo sin pedirlo. Va en .claude/settings.json:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
}
]
}
]
}
}
Necesita Node.js y jq, una herramienta pequeña para leer JSON que se instala aparte. Es un comando de Bash: en Windows funciona si tienes Git for Windows. Sin él, los hooks corren en PowerShell y tendrás que pedirle a Claude una versión para PowerShell. Cuando el hook funciona no ves ningún mensaje: abre el archivo y comprueba que quedó formateado.
Ejemplo 2: bloquear la edición de un archivo sensible
- Crea el script. En Mac o Linux, guárdalo como
.claude/hooks/proteger.shy hazlo ejecutable conchmod +x .claude/hooks/proteger.sh:#!/bin/bash ENTRADA=$(cat) ARCHIVO=$(echo "$ENTRADA" | jq -r '.tool_input.file_path // empty') ARCHIVO="${ARCHIVO//\\//}" for patron in ".env" "precios/"; do if [[ "$ARCHIVO" == *"$patron"* ]]; then echo "Bloqueado: $ARCHIVO es un archivo protegido" >&2 exit 2 fi done exit 0 - Regístralo en
.claude/settings.json:{ "hooks": { "PreToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/proteger.sh" } ] } ] } } - Pruébalo. Pídele a Claude que agregue un comentario al
.env. Tiene que frenar antes de editar y explicarte por qué.
El código de salida 2 bloquea la acción, y el mensaje del script le llega a Claude para que cambie de plan. El 0 no aprueba nada: deja que siga el flujo normal de permisos.
En Windows, guarda este script como .claude/hooks/proteger.ps1:
$entrada = [Console]::In.ReadToEnd() | ConvertFrom-Json
$archivo = $entrada.tool_input.file_path -replace '\\', '/'
if ($archivo -match '\.env$|/precios/') {
@{
hookSpecificOutput = @{
hookEventName = "PreToolUse"
permissionDecision = "deny"
permissionDecisionReason = "Archivo protegido: lo cambia una persona, no Claude"
}
} | ConvertTo-Json
} else {
exit 0
}
Y en el paso 2 reemplaza el bloque del comando por este:
{
"type": "command",
"command": "powershell.exe",
"args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File",
"${CLAUDE_PROJECT_DIR}/.claude/hooks/proteger.ps1"]
}
Para un bloqueo simple también existen las reglas de permisos, que administras con /permissions. El hook sirve cuando quieres una condición propia o un mensaje que explique el motivo.
Verifica
Escribe /hooks en Claude Code. Muestra todos los hooks activos, agrupados por evento y con el archivo de donde viene cada uno. Es solo de lectura: para cambiar algo, edita el archivo. Si el tuyo no aparece, revisa que el JSON sea válido y que el matcher esté bien escrito.
Seguridad: un hook es un programa
- Corre con tus permisos. Puede leer, modificar o borrar cualquier archivo al que tenga acceso tu usuario. Lee y prueba cada comando antes de agregarlo.
- Revisa los proyectos ajenos. Un repositorio puede traer hooks en su
.claude/settings.json. Claude Code no los ejecuta hasta que aceptas que confías en la carpeta, así que lee ese archivo antes de aceptar. - Un hook roto puede fallar en silencio. En el ejemplo 2, si jq no está instalado, el script no encuentra la ruta y deja pasar todo. Prueba el bloqueo antes de confiar en él.
- Para apagarlos todos, agrega
"disableAllHooks": truea tu archivo de configuración.
La lista completa de eventos y opciones está en la documentación oficial de hooks.