Hooks del ciclo de vida

Qué son los hooks y para qué sirven

Los hooks de Claude Code son comandos definidos por el usuario que se ejecutan automáticamente en puntos concretos del ciclo de vida del agente. A diferencia de las instrucciones en CLAUDE.md, que dependen de que el modelo las interprete correctamente, los hooks proporcionan un control determinista: se ejecutan siempre que se cumple la condición, sin variabilidad.

Los casos de uso más habituales incluyen:

• Formatear código automáticamente tras cada edición
• Bloquear operaciones antes de que se ejecuten (proteger archivos sensibles, validar comandos)
• Enviar notificaciones cuando Claude necesita atención
• Inyectar contexto tras una compactación para no perder información relevante
• Registrar actividad en logs de auditoría

Los hooks garantizan que ciertas acciones ocurran siempre, independientemente de lo que el modelo decida. Un hook de formateo se ejecutará tras cada edición sin excepción, mientras que una instrucción en CLAUDE.md podría no cumplirse en contextos largos.

Eventos disponibles

Claude Code dispone de más de una docena de eventos que cubren el ciclo de vida completo de una sesión. Los más utilizados son:

| Evento | Cuándo se dispara | |---|---| | PreToolUse | Antes de ejecutar una herramienta. Puede bloquearla | | PostToolUse | Después de que una herramienta se ejecute correctamente | | SessionStart | Al iniciar, reanudar o compactar una sesión | | Stop | Cuando Claude termina de responder | | Notification | Cuando Claude necesita la atención del usuario | | UserPromptSubmit | Cuando el usuario envía un prompt, antes de que Claude lo procese | | SubagentStart | Cuando se lanza un subagente | | SubagentStop | Cuando un subagente finaliza | | ConfigChange | Cuando un archivo de configuración cambia durante la sesión | | SessionEnd | Cuando la sesión termina | | PreCompact | Antes de la compactación del contexto |

Los eventos PreToolUse y PostToolUse son los más frecuentes en la práctica y cubren aproximadamente el 80% de los casos de uso habituales.

Configurar hooks en settings.json

Los hooks se definen dentro del bloque hooks de un archivo settings.json. Cada evento contiene un array de reglas, y cada regla tiene un matcher (filtro) y uno o más hooks a ejecutar.

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

Este ejemplo ejecuta Prettier tras cada operación de edición o escritura de archivos. El matcher "Edit|Write" es una expresión regular que filtra por nombre de herramienta, de forma que el hook solo se dispara cuando Claude usa Edit o Write, no cuando usa Bash, Read u otra herramienta.

Ubicación de la configuración

La ubicación del archivo settings.json determina el alcance del hook:

| Ubicación | Alcance | Compartido | |---|---|---| | ~/.claude/settings.json | Todos tus proyectos | No | | .claude/settings.json | Proyecto actual | Si, via Git | | .claude/settings.local.json | Proyecto actual | No (gitignored) |

También se puede usar el menú interactivo /hooks dentro de Claude Code para crear, editar y eliminar hooks sin tocar el JSON directamente.

Entrada y salida de hooks

Los hooks se comunican con Claude Code mediante stdin, stdout, stderr y códigos de salida.

Datos de entrada

Cuando un evento se dispara, Claude Code envía datos en formato JSON al stdin del script. Por ejemplo, un hook PreToolUse que intercepta un comando Bash recibe:

{
  "session_id": "abc123",
  "cwd": "/Users/dev/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

Códigos de salida

El código de salida determina la acción:

• Exit 0: la operación procede con normalidad. Para eventos como SessionStart y UserPromptSubmit, lo que se escriba en stdout se añade al contexto de Claude.
• Exit 2: la operación se bloquea. El mensaje escrito en stderr se envía a Claude como feedback para que ajuste su comportamiento.
• Cualquier otro código: la operación procede y el stderr se registra en logs (visible con modo verbose Ctrl+O).

Patrones prácticos

Auto-formatear código tras ediciones

Este hook ejecuta Prettier en cada archivo que Claude modifica:

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

El comando extrae la ruta del archivo editado con jq y la pasa a Prettier. Este hook se almacena en .claude/settings.json para que aplique a todo el proyecto.

Proteger archivos sensibles

Un hook PreToolUse puede impedir que Claude modifique archivos críticos como .env o package-lock.json. En este caso se usa un script externo que el hook invoca:

#!/bin/bash
# .claude/hooks/protect-files.sh

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

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Bloqueado: $FILE_PATH coincide con el patrón protegido '$pattern'" >&2
    exit 2
  fi
done

exit 0

La configuración en settings.json:

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

La variable $CLAUDE_PROJECT_DIR apunta al directorio raíz del proyecto, lo que permite referenciar scripts con rutas relativas al proyecto independientemente del directorio de trabajo actual.

Notificaciones de escritorio

Un hook Notification envía una alerta nativa del sistema operativo cuando Claude termina de trabajar y necesita input:

macOS:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code necesita tu atención\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Linux:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code necesita tu atención'"
          }
        ]
      }
    ]
  }
}

Reinyectar contexto tras compactación

Cuando la ventana de contexto se llena y Claude compacta la conversación, se pueden perder detalles importantes. Un hook SessionStart con matcher compact reinyecta información crítica tras cada compactación:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Recordatorio: usar Bun en lugar de npm. Ejecutar bun test antes de cada commit. Sprint actual: refactorización de auth.'"
          }
        ]
      }
    ]
  }
}

Lo que el script escriba en stdout se añade al contexto de Claude tras la compactación.

Matchers y filtrado

Los matchers determinan cuándo se dispara un hook dentro de su evento. Sin matcher (cadena vacia), el hook se ejecuta en cada ocurrencia del evento. Cada tipo de evento filtra por un campo diferente:

| Evento | Campo que filtra el matcher | Ejemplos | |---|---|---| | PreToolUse, PostToolUse | Nombre de la herramienta | Bash, Edit\|Write, mcp__.* | | SessionStart | Tipo de inicio | startup, resume, compact | | Notification | Tipo de notificación | permission_prompt, idle_prompt | | SubagentStart, SubagentStop | Tipo de agente | Explore, Plan, nombres custom | | ConfigChange | Fuente de configuración | user_settings, project_settings |

Los matchers soportan expresiones regulares, lo que permite patrones como mcp__github__.* para interceptar todas las herramientas del servidor MCP de GitHub.

Hooks de tipo prompt y agent

Además de los hooks de tipo command (los más habituales), Claude Code soporta otros tipos para decisiones que requieren juicio en lugar de reglas deterministas.

Hooks de tipo prompt

Un hook de tipo prompt envía los datos del evento a un modelo Claude (Haiku por defecto) que evalúa la situación y devuelve una decisión:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Verifica si todas las tareas solicitadas están completas. Si no, responde con {\"ok\": false, \"reason\": \"lo que falta por hacer\"}."
          }
        ]
      }
    ]
  }
}

Si el modelo devuelve "ok": false, Claude recibe el motivo como feedback y continúa trabajando.

Hooks de tipo agent

Los hooks de tipo agent lanzan un subagente que puede leer archivos, buscar código y ejecutar herramientas para verificar condiciones antes de tomar una decisión:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verifica que todos los tests unitarios pasan. Ejecuta la suite de tests y comprueba los resultados. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Hooks HTTP

Los hooks de tipo http envían los datos del evento mediante POST a un endpoint HTTP, en lugar de ejecutar un comando local. Son útiles para servicios de auditoría centralizados o integraciones con sistemas externos:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

Los hooks de tipo command cubren la gran mayoría de necesidades. Los tipos prompt y agent son útiles cuando la decisión de bloquear o permitir una acción requiere análisis contextual que no se puede expresar con reglas fijas.

Configuración interactiva con /hooks

El comando /hooks dentro de una sesión interactiva ofrece una interfaz visual para gestionar hooks sin editar JSON manualmente. Permite:

• Ver todos los hooks configurados agrupados por evento
• Crear nuevos hooks seleccionando evento, matcher y comando
• Elegir la ubicación de almacenamiento (usuario, proyecto o local)
• Activar o desactivar todos los hooks de forma global

Los hooks creados mediante /hooks se aplican inmediatamente. Las ediciones manuales del archivo settings.json requieren reiniciar la sesión o abrir /hooks para recargarlos.

Para depurar hooks, el modo verbose (Ctrl+O) muestra la salida de cada hook en el transcrito de la sesión. El flag --debug al lanzar Claude Code proporciona información detallada sobre qué hooks coincidieron y sus códigos de salida.