Hooks de Claude Code: guía esencial con 6 configuraciones para copiar (2026)

Los hooks de Claude Code que conviene añadir primero son seis: un aviso de escritorio, formato automático tras cada edición, protección para archivos como .env, volver a meter el contexto tras compactar, un registro de cada comando Bash y una comprobación de tests antes de que Claude pare. Los cinco primeros son hooks de comando normales que puedes pegar tal cual. El último usa un agent hook, que Anthropic marca como experimental. La diferencia con una Skill es sencilla: la Skill es algo que Claude lee y puede seguir o no; el hook se ejecuta siempre que salta su evento.

Todas las configuraciones salen de la guía oficial de hooks y de la referencia de hooks de Anthropic, revisadas el 27 de octubre de 2026. Si aún no tienes claro qué hace cada pieza, empieza por Claude Code Skills vs MCP.

Seis hooks para empezar

Cada hook tiene tres partes: el evento (cuándo se ejecuta), el matcher (a qué herramienta o caso se aplica) y el comando. Van dentro de la clave hooks de un archivo de configuración, y un mismo evento puede tener varios hooks.

1. Aviso de escritorio cuando Claude te espera

Cuando Claude necesita un permiso o espera tu respuesta, recibes una notificación del sistema y no tienes que vigilar la terminal. Esta es la versión para macOS, en ~/.claude/settings.json. En Linux usa notify-send y en Windows un aviso de PowerShell; la documentación trae las tres.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Con el matcher vacío salta con cualquier tipo de notificación. Con permission_prompt solo te avisa de las aprobaciones, unos seis segundos después de que aparezca la petición. idle_prompt salta cuando Claude terminó y llevas unos 60 segundos sin escribir. Si en Mac no aparece nada, lo más probable es que Script Editor no tenga permiso de notificaciones; actívalo en Ajustes del Sistema > Notificaciones.

2. Formato automático tras cada edición

Cada vez que Claude edita o escribe un archivo, Prettier pasa por ese archivo. Va en el .claude/settings.json del proyecto para que lo use todo el equipo (ejemplo oficial). Necesita jq instalado.

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

Solo cubre las herramientas Edit y Write. Los archivos que Claude cambia con un comando Bash no lo activan; para eso la documentación propone un hook FileChanged.

3. Proteger .env y los archivos de bloqueo

Este es el que más merece la pena. PreToolUse se ejecuta antes que la herramienta. Si el script termina con código 2, la edición se bloquea y lo que el script escribió en stderr le llega a Claude como explicación (ejemplo oficial). Guarda el script como .claude/hooks/protect-files.sh y dale permisos con chmod +x:

#!/bin/bash
# .claude/hooks/protect-files.sh
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
FILE_PATH="${FILE_PATH//\\//}"
PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")
for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done
exit 0

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" }
        ]
      }
    ]
  }
}

Para cambiar qué se protege, edita la línea PROTECTED_PATTERNS. La documentación también indica que el deny de un hook se respeta en todos los modos de permisos, incluido bypassPermissions, así que es una regla más firme que una línea en CLAUDE.md.

4. Recuperar el contexto tras compactar

Cuando la conversación se alarga, Claude Code la compacta y se pueden perder detalles. Un hook SessionStart con el matcher compact vuelve a añadir tus reglas después de cada compactación (ejemplo oficial). Lo que el hook imprime en stdout entra en el contexto de Claude.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          { "type": "command", "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing.'" }
        ]
      }
    ]
  }
}

Cambia el texto del echo por tus reglas, o por un comando como git log –oneline -5 para incluir los últimos commits. Para lo que quieras en todas las sesiones, la documentación recomienda usar CLAUDE.md.

5. Registrar cada comando Bash

La forma más sencilla de revisar después qué ejecutó Claude. PostToolUse salta cuando el comando termina bien y lo añade a un archivo de log:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt" }
        ]
      }
    ]
  }
}

Solo registra los comandos que salieron bien. Para los que fallan hace falta otro hook en PostToolUseFailure.

6. Revisar los tests antes de que Claude pare

El evento Stop salta cuando Claude termina de responder. Un agent hook lanza un subagente que ejecuta los tests y, si fallan, devuelve a Claude al trabajo (ejemplo oficial). Por defecto un agent hook tiene 60 segundos de límite; aquí se sube a 120.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Tres avisos. Primero, Stop no admite matcher y salta cada vez que Claude termina una respuesta, no solo al acabar la tarea. Segundo, los agent hooks son experimentales y la documentación recomienda hooks de comando para flujos de producción. Tercero, Claude Code deja de hacer caso a un hook Stop que bloquea ocho veces seguidas sin ninguna llamada a herramientas entre medias. Si escribes tu propio hook Stop de comando, revisa el campo stop_hook_active y sal en cuanto sea true (documentación).

Los eventos que vas a usar

La guía lista 33 eventos, pero con los seis de la tabla se cubre casi todo. PreToolUse puede frenar una acción antes de que ocurra. PostToolUse llega cuando la herramienta ya se ejecutó, así que no puede deshacer nada (limitaciones).

Si varios hooks coinciden con el mismo evento, se ejecutan en paralelo y sus resultados se combinan. En PreToolUse gana la respuesta más restrictiva, en este orden: deny, defer, ask, allow (documentación). Así un hook de registro y uno de bloqueo pueden convivir: el bloqueo se aplica y el log se escribe igual.

En qué archivo va cada hook

Lo personal, como el aviso de escritorio, va en ~/.claude/settings.json. Las reglas del equipo, como proteger archivos o el formato, van en el .claude/settings.json del proyecto y se suben al repositorio. Para las rutas exactas y qué archivo manda sobre cuál, mira dónde está el settings.json de Claude Code.

Después de guardar, escribe /hooks en Claude Code para ver todos los hooks cargados agrupados por evento (documentación). Para apagarlos todos un rato, añade «disableAllHooks»: true a la configuración.

Los hooks también pueden venir dentro de un plugin, en su hooks/hooks.json, y funcionan mientras el plugin esté activo. Para plugins ya hechos mira los mejores mods de Claude Code, y para crear el tuyo, cómo escribir un plugin de Claude Code.

Revisa la seguridad antes de pegar

La documentación lo dice claro: los hooks de comando ejecutan comandos de shell con todos los permisos de tu usuario y pueden modificar, borrar o leer cualquier archivo al que llegue tu cuenta (consideraciones de seguridad). Lee cada línea de un hook copiado de internet antes de añadirlo. Con los plugins igual: mira su hooks/hooks.json antes de activarlo.

Además, los hooks de comando tienen un límite de 10 minutos por defecto. Formateadores y linters van bien, pero no metas en un hook nada que se quede esperando a que escribas.

Preguntas frecuentes

¿Qué hooks de Claude Code añado primero?

Empieza por el hook PreToolUse que protege archivos. Bloquea cambios en .env, .git/ y rutas parecidas, y funciona en todos los modos de permisos. El aviso de escritorio va justo después, porque la diferencia se nota enseguida.

¿Por qué no se ejecuta mi hook?

Escribe /hooks y mira si aparece bajo el evento correcto. Si no aparece, busca una coma de más en el JSON o una ruta mal escrita. Si aparece, comprueba que el matcher coincide exactamente con el nombre de la herramienta, porque distingue mayúsculas y minúsculas. Los hooks con script también necesitan chmod +x.

¿Un hook puede ejecutar un comando con barra?

No. Los hooks de comando solo se comunican con Claude Code mediante stdout, stderr y códigos de salida; no pueden lanzar comandos / ni llamar a herramientas (limitaciones). Cuando la decisión necesita criterio, usa un hook de tipo prompt o agent.

Los seis hooks de Claude Code de esta guía salen de los ejemplos oficiales y funcionan por separado. Añade uno, confírmalo con /hooks y luego pasa al siguiente. Los matchers también sirven para herramientas MCP; para elegir los servidores mira los mejores MCP para Claude Code.