Hooks de Claude Code: tres para pegar hoy

Un hook es un comando de shell que Claude Code ejecuta en un punto fijo, como después de una edición o antes de usar una herramienta. Pasa siempre, se acuerde o no el modelo.

Dónde va un hook

• ~/.claude/settings.json: todos tus proyectos, solo en tu máquina.
• .claude/settings.json: un proyecto; se puede subir a git y compartir.
• .claude/settings.local.json: un proyecto, solo tuyo.

Cada evento es una clave dentro de un único objeto hooks, así que añade el evento nuevo junto a los que ya hay, no encima. Escribe /hooks en una sesión para ver lo que hay configurado.

1. Un aviso cuando Claude te necesita

El evento Notification salta cuando Claude espera una respuesta o un permiso. En Linux:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

En Windows, cambia el comando por este. Abre un cuadro de diálogo, que puede quedar detrás de tu terminal:

"command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""

En macOS usa osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'. El matcher vacío salta con todos los tipos de aviso. Usa permission_prompt para que salte solo cuando Claude espera que apruebes algo, o idle_prompt cuando terminó y llevas cerca de un minuto sin escribir.

2. Dar formato a los archivos que edita Claude

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

El hook recibe el evento como JSON por stdin. jq saca la ruta del archivo editado y Prettier lo reescribe. El matcher lo limita a las herramientas que editan archivos. Necesitas tener jq instalado. Si el hook funciona no imprime nada, así que mira el archivo, no la conversación. Un hook PostToolUse corre después de la edición, así que no puede deshacer nada.

3. Bloquear la edición de archivos protegidos

Guárdalo como .claude/hooks/protect-files.sh:

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

for pattern in ".env" "package-lock.json" ".git/"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

En macOS y Linux ejecuta chmod +x .claude/hooks/protect-files.sh. Después regístralo en .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

En Windows las rutas llegan con barras invertidas, así que normalízalas a barras normales antes de comparar, como hace la versión de Anthropic de este script.

Cómo responde un hook

• Entrada: el evento como JSON por stdin. En una llamada a Bash, tool_input.command trae el comando. En una edición de archivo, tool_input.file_path trae la ruta.
• Salida 0: sin objeción. En PreToolUse eso no es aprobar; sigue el flujo normal de permisos.
• Salida 2: bloquea, y lo que escribas en stderr vuelve a Claude para que cambie de rumbo.
• JSON por stdout con salida 0 da más control, por ejemplo un deny con motivo. Elige salida 2 o JSON para cada hook, no las dos.

¿Hook, regla o CLAUDE.md?

Una línea en CLAUDE.md es una petición. Una regla de permisos la aplica el programa. Un hook PreToolUse puede hacer lo mismo con tu propia lógica, y su deny se mantiene en todos los modos de permisos, incluido bypassPermissions, según la documentación de Anthropic.

Límites

• Un hook es un comando de shell que corre con tus permisos. Léelo antes de añadirlo, como cualquier script.
• Los hooks Stop saltan cada vez que Claude termina de responder, no solo cuando acaba toda la tarea.
• Los hooks de comando hablan solo por stdout, stderr y códigos de salida. No pueden ejecutar comandos con / ni llamar a herramientas.
• Si un hook no salta, ejecuta /hooks para confirmar que está bajo el evento correcto y comprueba que el matcher coincide exactamente con el nombre de la herramienta. Los matchers distinguen mayúsculas.

Comprueba que funciona

1. Añade un hook cada vez a .claude/settings.local.json de un proyecto de pruebas.
2. Ejecuta /hooks y confirma que sale bajo el evento correcto.
3. Dispáralo a propósito: pide a Claude que edite un archivo .env o que añada una línea mal formateada.

Esta página sigue la guía de hooks de Anthropic tal como la leemos en octubre de 2026. Esa página manda, y no tenemos relación con Anthropic. La escribimos a partir de la documentación y no hemos probado todos los ejemplos en todos los sistemas.

Si quieres una segunda mirada a tu CLAUDE.md y a tus ajustes, el Tune-Up Kit es una lista de comprobación para eso (la ficha está en inglés).

Mira también: Trabajar hacia un objetivo con /goal.