Automatizar acciones con hooks

Ejecuta comandos de shell automáticamente cuando Claude Code edita archivos, finaliza tareas o necesita entrada. Formatea código, envía notificaciones, valida comandos y aplica reglas del proyecto.

Los hooks son comandos de shell definidos por el usuario. Claude Code los ejecuta en puntos específicos de su ciclo de vida, lo que le proporciona control determinista: ciertas acciones siempre ocurren en lugar de depender de que el LLM elija ejecutarlas. Utilice hooks para aplicar reglas del proyecto, automatizar tareas repetitivas e integrar Claude Code con sus herramientas existentes.

Para decisiones que requieren criterio en lugar de reglas deterministas, también puedes usar hooks basados en prompts o hooks basados en agentes que utilizan un modelo Claude para evaluar condiciones.

Para otras formas de extender Claude Code, consulta skills para dar a Claude instrucciones adicionales y comandos ejecutables, subagents para ejecutar tareas en contextos aislados, y plugins para empaquetar extensiones para compartir entre proyectos.

Configura tu primer hook

Para crear un hook, añade un bloque hooks a un archivo de configuración. Este tutorial crea un hook de notificación de escritorio, para que recibas una alerta cada vez que Claude esté esperando tu entrada en lugar de ver la terminal.

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

{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
}
],
"Notification": [
{
"matcher": "",
"hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" }]
}
]
}
}

Qué puedes automatizar

Los hooks te permiten ejecutar código en puntos clave del ciclo de vida de Claude Code: formatear archivos después de ediciones, bloquear comandos antes de que se ejecuten, enviar notificaciones cuando Claude necesita entrada, inyectar contexto al inicio de la sesión, y más. Para la lista completa de eventos de hook, consulta la referencia de Hooks.

Cada ejemplo incluye un bloque de configuración listo para usar que añades a un archivo de configuración.

Para un ejemplo de producción de hooks que ejecutan una revisión de modelo separada y alimentan los hallazgos de vuelta a la sesión, consulta cómo el plugin security-guidance se integra con Claude Code.

Recibe notificaciones cuando Claude necesita entrada

Obtén una notificación de escritorio cada vez que Claude termine de trabajar y necesite tu entrada, para que puedas cambiar a otras tareas sin verificar la terminal.

Este hook usa el evento Notification, que Claude Code activa cuando Claude está esperando entrada o permiso. Consulta cuándo se activa cada tipo de notificación para el momento exacto. Cada pestaña a continuación usa el comando de notificación nativo de la plataforma. Añade esto a ~/.claude/settings.json:

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

osascript -e 'display notification "test"'

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

notify-send 'Claude Code' 'test'

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

El matcher vacío se activa en todos los tipos de notificación. Para activarse solo en eventos específicos, establécelo en uno de estos valores:

Claude Code cronometra permission_prompt de manera diferente en una terminal y en Claude Desktop, la extensión de VS Code y otros hosts que responden solicitudes de permiso a través del Agent SDK. Consulta cuándo se activa cada tipo de notificación para ambos tiempos.

Los matchers agent_needs_input y agent_completed requieren Claude Code v2.1.198 o posterior.

Los matchers quota_auto_resume_fired, quota_auto_resume_stale y quota_auto_resume_disabled requieren Claude Code v2.1.234 o posterior.

En sesiones de terminal, permission_prompt para una solicitud de red de un comando en sandbox requiere Claude Code v2.1.246 o posterior.

agent_needs_input para una pregunta de configuración de terminal de un compañero de equipo requiere Claude Code v2.1.248 o posterior.

Escribe /hooks y selecciona Notification para confirmar que el hook está registrado. Para el esquema de evento completo, consulta la referencia de Notification.

Formatea automáticamente el código después de ediciones

Ejecuta automáticamente Prettier en cada archivo que Claude edita, para que el formato se mantenga consistente sin intervención manual.

Este hook usa el evento PostToolUse con un matcher Edit|Write, por lo que se ejecuta solo después de herramientas de edición de archivos. El comando extrae la ruta del archivo editado con jq y la pasa a Prettier. Añade esto a .claude/settings.json en la raíz de tu proyecto:

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

Para probar el hook, pídele a Claude que añada una línea con cadenas entre comillas simples a un archivo JavaScript, luego abre el archivo: con la configuración predeterminada de Prettier, el hook las reescribe a comillas dobles.

Cuando el hook tiene éxito, Claude Code no muestra nada en la conversación. Para confirmar que el hook se ejecutó, verifica que el archivo editado esté reformateado, o consulta Técnicas de depuración.

Para reformatear un archivo específico sin importar cómo cambie, incluyendo cuando un comando Bash lo reescribe, usa un hook FileChanged en su lugar.

Bloquea ediciones a archivos protegidos

Evita que Claude modifique archivos sensibles como .env, package-lock.json, o cualquier cosa en .git/. Claude recibe retroalimentación explicando por qué se bloqueó la edición, para que pueda ajustar su enfoque.

Este ejemplo usa un archivo de script separado que el hook llama. El script verifica la ruta del archivo de destino contra una lista de patrones protegidos y sale con código 2 para bloquear la edición.

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

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

# Normaliza separadores de barra invertida de Windows para que los patrones a continuación coincidan
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

chmod +x .claude/hooks/protect-files.sh

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

Reinyecta contexto después de compactación

Cuando la ventana de contexto de Claude se llena, la compactación resume la conversación para liberar espacio. Esto puede perder detalles importantes. Usa un hook SessionStart con un matcher compact para reinyectar contexto crítico después de cada compactación.

Claude Code añade texto plano que tu comando escribe en stdout al contexto de Claude. Este ejemplo recuerda a Claude las convenciones del proyecto y el trabajo reciente. Añade esto a .claude/settings.json en la raíz de tu proyecto:

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

Puedes reemplazar el echo con cualquier comando que produzca salida dinámica, como git log --oneline -5 para mostrar commits recientes. Para inyectar contexto en cada inicio de sesión, considera usar CLAUDE.md en su lugar. Para variables de entorno, consulta CLAUDE_ENV_FILE en la referencia.

Audita cambios de configuración

Realiza un seguimiento de cuándo los archivos de configuración o skills cambian durante una sesión. El evento ConfigChange se activa cuando un proceso externo o editor modifica un archivo de configuración, para que puedas registrar cambios para cumplimiento o bloquear modificaciones no autorizadas.

Este ejemplo añade cada cambio a un registro de auditoría. Añade esto a ~/.claude/settings.json:

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

El matcher filtra por tipo de configuración: user_settings, project_settings, local_settings, policy_settings, o skills. Para bloquear que un cambio tenga efecto, sal con código 2 o devuelve {"decision": "block"}. Consulta la referencia de ConfigChange para el esquema de entrada completo.

Para confirmar que el hook registra cambios, edita un archivo de configuración en otro editor mientras una sesión está en ejecución, luego abre ~/claude-config-audit.log: el hook añade una línea JSON por cambio con la marca de tiempo, fuente y ruta del archivo.

Recarga el entorno cuando el directorio o los archivos cambian

Algunos proyectos establecen diferentes variables de entorno dependiendo de en qué directorio estés. Herramientas como direnv hacen esto automáticamente en tu shell, pero la herramienta Bash de Claude no recoge esos cambios por sí sola.

Emparejar un hook SessionStart con un hook CwdChanged arregla esto. SessionStart carga las variables para el directorio en el que lanzas, y CwdChanged las recarga cada vez que Claude cambia de directorio. Ambos escriben en CLAUDE_ENV_FILE, que Claude Code ejecuta como un preámbulo de script antes de cada comando Bash. Añade esto a ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ],
    "CwdChanged": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

Ejecuta direnv allow una vez en cada directorio que tenga un .envrc para que direnv tenga permiso de cargarlo. Si usas devbox o nix en lugar de direnv, el mismo patrón funciona con devbox shellenv o devbox global shellenv en lugar de direnv export bash.

Para reaccionar a archivos específicos en lugar de cada cambio de directorio, usa FileChanged con un matcher listando los nombres de archivo a observar, separados por |. Cuando construyas la lista de observación, Claude Code divide este valor en nombres de archivo literales en lugar de evaluarlo como una expresión regular. Consulta FileChanged para cómo el mismo valor también filtra qué grupos de hooks se ejecutan cuando un archivo cambia. Este ejemplo observa .envrc y .env en el directorio de trabajo:

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": ".envrc|.env",
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

Consulta las entradas de referencia CwdChanged y FileChanged para esquemas de entrada, salida watchPaths, y detalles de CLAUDE_ENV_FILE.

Aprueba automáticamente avisos de permiso específicos

Omite el diálogo de aprobación para llamadas a herramientas que siempre permites. Este ejemplo aprueba automáticamente ExitPlanMode, la herramienta que Claude llama cuando termina de presentar un plan y pide proceder, para que no se te solicite cada vez que un plan esté listo.

A diferencia de los ejemplos de código de salida anteriores, la aprobación automática requiere que tu hook escriba una decisión JSON en stdout. Claude Code ejecuta hooks PermissionRequest cuando está a punto de pedirte permiso, y si tu hook devuelve "behavior": "allow", Claude Code responde la solicitud en tu nombre.

El matcher limita el hook a ExitPlanMode solamente, para que ningún otro aviso se vea afectado. Añade esto a ~/.claude/settings.json:

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PermissionRequest\", \"decision\": {\"behavior\": \"allow\"}}}'"
          }
        ]
      }
    ]
  }
}

Cuando el hook aprueba, Claude Code sale del modo plan y restaura cualquier modo de permiso que estuviera activo antes de entrar en modo plan. La transcripción muestra "Allowed by PermissionRequest hook" donde habría aparecido el diálogo. La ruta del hook siempre mantiene la conversación actual: no puede limpiar contexto e iniciar una sesión de implementación fresca de la manera que el diálogo puede.

Para establecer un modo de permiso específico en su lugar, la salida de tu hook puede incluir un array updatedPermissions con una entrada setMode. El valor mode es cualquier modo de permiso como default, acceptEdits, o bypassPermissions, y destination: "session" lo aplica solo para la sesión actual.

Para cambiar la sesión a acceptEdits, tu hook escribe este JSON en stdout:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedPermissions": [
        { "type": "setMode", "mode": "acceptEdits", "destination": "session" }
      ]
    }
  }
}

Mantén el matcher lo más estrecho posible. Coincidir con .* o dejar el matcher vacío aprobaría automáticamente cada aviso de permiso de herramienta, incluyendo escrituras de archivos y comandos de shell. Consulta la referencia de PermissionRequest para el conjunto completo de campos de decisión.

Cómo funcionan los hooks

Claude Code dispara eventos de hook en puntos específicos de su ciclo de vida. Cuando se dispara un evento, Claude Code ejecuta todos los hooks coincidentes en paralelo; consulta Campos del manejador de hooks para saber cómo se tratan los manejadores duplicados. La tabla a continuación muestra cada evento y cuándo se dispara:

Cada hook tiene un type que determina cómo se ejecuta. La mayoría de los hooks usan "type": "command", que ejecuta un comando de shell. Hay otros cuatro tipos disponibles:

• "type": "http": POST de datos de evento a una URL. Consulta HTTP hooks.
• "type": "mcp_tool": llamar a una herramienta en un servidor MCP ya conectado. Consulta MCP tool hooks.
• "type": "prompt": evaluación LLM de un solo turno. Consulta Prompt-based hooks.
• "type": "agent": verificación multi-turno con acceso a herramientas. Los hooks de agente son experimentales y pueden cambiar. Consulta Agent-based hooks.

Combina resultados de múltiples hooks

Cuando múltiples hooks coinciden con el mismo evento, el comando de cada hook se ejecuta hasta completarse antes de que Claude Code fusione los resultados. Un hook que devuelve deny no detiene la ejecución de hooks hermanos. No confíes en que el deny de un hook suprima efectos secundarios en otro hook.

Después de que todos los hooks coincidentes terminen, Claude Code combina sus salidas. Para decisiones de permiso PreToolUse, la respuesta más restrictiva gana, en el orden deny, defer, ask, allow. El texto de additionalContext se mantiene de cada hook y se pasa a Claude junto.

El ejemplo a continuación registra dos hooks PreToolUse en Bash. El primero añade cada comando a un archivo de registro y sale con 0. El segundo ejecuta un script que sale con 2 para negar cuando el comando contiene rm -rf:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r .tool_input.command >> ~/.claude/bash.log"
          },
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm-rf.sh"
          }
        ]
      }
    ]
  }
}

Cuando Claude intenta ejecutar rm -rf /tmp/build, ambos hooks se ejecutan en paralelo. El hook de registro escribe el comando en ~/.claude/bash.log y sale con 0, lo que no reporta ninguna decisión. El hook de protección sale con 2, lo que niega la llamada a herramienta. El deny gana, por lo que Claude Code bloquea el comando y muestra a Claude el stderr del guardrail. La entrada de registro se sigue escribiendo porque el hook de registro ya se ejecutó.

Lee entrada y devuelve salida

Los hooks se comunican con Claude Code a través de stdin, stdout, stderr y códigos de salida. Cuando se activa un evento, Claude Code pasa datos específicos del evento como JSON a stdin de tu script. Tu script lee esos datos, hace su trabajo, y le dice a Claude Code qué hacer a continuación a través del código de salida.

Entrada del hook

Cada evento incluye campos comunes como session_id, un ID único para la sesión, y cwd, el directorio de trabajo cuando se disparó el evento, pero cada tipo de evento añade datos diferentes. Cuando Claude ejecuta un comando Bash, un hook PreToolUse recibe estos campos en stdin:

• hook_event_name: el evento que activó el hook
• tool_name: la herramienta que Claude está a punto de usar
• tool_input: los argumentos que Claude pasó a la herramienta. Para Bash, su campo command contiene el comando de shell.

Por ejemplo, la entrada del hook para un comando npm test se ve así:

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

Tu script puede analizar ese JSON y actuar sobre cualquiera de esos campos. Los hooks UserPromptSubmit obtienen el texto prompt en su lugar, los hooks SessionStart obtienen una source de startup, resume, clear, compact, o fork, y así sucesivamente. Consulta Campos de entrada comunes en la referencia para campos compartidos, y la sección de cada evento para esquemas específicos del evento.

Salida del hook

Tu script le dice a Claude Code qué hacer a continuación escribiendo en stdout o stderr y saliendo con un código específico. El siguiente hook PreToolUse bloquea un comando:

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

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  # stderr se convierte en retroalimentación de Claude
  exit 2 # exit 2 = bloquea la acción
fi

exit 0  # exit 0 = no hay objeción; el flujo de permiso normal se aplica

El código de salida determina qué sucede a continuación:

• Exit 0: tu hook reporta sin objeción a través de su código de salida.
  • Para un hook PreToolUse esto no aprueba la llamada a herramienta: el flujo de permiso normal aún se aplica.
  • Para hooks UserPromptSubmit, UserPromptExpansion, SessionStart, y PostModelSwitch, Claude Code añade stdout que trata como texto plano al contexto de Claude.
• Exit 2: Claude Code bloquea la acción. Escribe una razón en stderr. Dónde llega depende del evento: algunos eventos lo alimentan a Claude como retroalimentación para que pueda ajustar, otros lo muestran al usuario, y algunos, como ConfigChange y Elicitation, no muestran ningún mensaje. Algunos eventos no pueden ser bloqueados: para SessionStart y otros, exit 2 muestra stderr al usuario y la ejecución continúa. Consulta comportamiento del código de salida 2 por evento para la lista completa.
• Cualquier otro código de salida: para la mayoría de eventos, el resultado depende de lo que tu hook imprimió en stdout:
  • Un objeto analizado que pasa validación de esquema: Claude Code ignora el código de salida, el JSON solo decide el resultado, y el hook no se reporta como un error. Las excepciones por evento, como WorktreeCreate fallando en cualquier salida distinta de cero, se enumeran en la sección Salida del código de salida de la referencia.
  • Un objeto analizado que falla validación de esquema, o stdout que Claude Code intenta analizar como JSON pero que no es JSON válido: un error sin bloqueo; el aviso lleva el mensaje de validación o análisis.
  • Stdout que Claude Code trata como texto plano, o stdout vacío: la acción procede como un error sin bloqueo. La transcripción muestra un aviso <hook name> hook error, luego la primera línea de stderr prefijada con Failed with non-blocking status code:. Para capturar el stderr completo, habilita registro de depuración con claude --debug o ejecutando /debug en medio de la sesión.

Salida JSON estructurada

Los códigos de salida solo te permiten bloquear o permanecer en silencio. Para más control, sal con 0 e imprime un objeto JSON a stdout en su lugar.

Por ejemplo, un hook PreToolUse puede negar una llamada a herramienta y decirle a Claude por qué, o escalarla al usuario para aprobación:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

Con "deny", Claude Code cancela la llamada a herramienta y alimenta permissionDecisionReason de vuelta a Claude.

En PreToolUse, Claude Code maneja cada valor permissionDecision de la siguiente manera:

• "allow": omite el aviso de permiso interactivo. Las reglas de negación y solicitud, incluyendo listas de negación gestionadas empresariales, aún se aplican, al igual que los avisos para herramientas MCP marcadas requiresUserInteraction y para herramientas de conector que tu organización configuró como ask en sesiones donde esa configuración llega a Claude Code
• "deny": cancela la llamada a herramienta y envía la razón a Claude
• "ask": muestra el aviso de permiso al usuario como es normal

Un cuarto valor, "defer", está disponible en modo no interactivo con la bandera -p. Sale del proceso con la llamada a herramienta preservada para que un envoltorio del SDK del Agente pueda recopilar entrada y reanudar. Consulta Defer a tool call for later en la referencia.

Un hook PreModelSwitch devuelve el mismo campo permissionDecision: "allow" permite que un cambio de modelo proceda, y "deny" lo cancela. "ask" te hace confirmar el cambio cuando ejecutas /model en una sesión interactiva; en cualquier otro lugar, Claude Code trata "ask" como un rechazo. Consulta PreModelSwitch decision control.

Otros eventos usan patrones de decisión diferentes. Por ejemplo, los hooks PostToolUse y Stop usan un campo decision: "block" de nivel superior, mientras que PermissionRequest usa hookSpecificOutput.decision.behavior. Consulta la tabla de resumen en la referencia para un desglose completo por evento.

Para hooks UserPromptSubmit, usa hookSpecificOutput.additionalContext en su lugar para inyectar texto en el contexto de Claude. Anida additionalContext dentro de hookSpecificOutput; si lo colocas en el nivel superior del JSON, Claude Code lo ignora silenciosamente. Por ejemplo, esta salida añade el estado de rama actual a cada aviso:

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Current branch: release-42. Deploy freeze until Friday."
  }
}

Consulta UserPromptSubmit decision control para la forma de salida completa, incluyendo bloqueo de avisos y configuración del título de sesión.

Los hooks con type: "prompt" manejan la salida de manera diferente: consulta Prompt-based hooks.

Filtra hooks con matchers

Sin un matcher, un hook se activa en cada ocurrencia de su evento. Los matchers te permiten estrecharlo. Por ejemplo, si quieres ejecutar un formateador solo después de ediciones de archivos, no después de cada llamada a herramienta, añade un matcher a tu hook PostToolUse:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "prettier --write ..." }
        ]
      }
    ]
  }
}

El matcher "Edit|Write" se activa solo cuando Claude usa la herramienta Edit o Write, no cuando usa Bash, Read, u otra herramienta. En Claude Code v2.1.191 o posterior, una coma separa alternativas de la misma manera, por lo que "Edit, Write" es equivalente. Consulta Matcher patterns para cómo se evalúan los nombres simples y las expresiones regulares.

Cada tipo de evento coincide en un campo específico:

Las pestañas a continuación muestran algunos matchers más en diferentes tipos de eventos.

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

{
"hooks": {
"PreToolUse": [
{
"matcher": "mcp__github__.*",
"hooks": [
{
"type": "command",
"command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
}
]
}
]
}
}

{
"hooks": {
"SessionEnd": [
{
"matcher": "clear",
"hooks": [
{
"type": "command",
"command": "rm -f /tmp/claude-scratch-*.txt"
}
]
}
]
}
}

Filtra por nombre de herramienta y argumentos con el campo `if`

El campo if usa sintaxis de regla de permiso para filtrar hooks por nombre de herramienta y argumentos juntos, para que el proceso del hook solo se genere cuando la llamada a herramienta coincida. Esto va más allá de matcher, que filtra a nivel de grupo solo por nombre de herramienta.

Por ejemplo, esta configuración ejecuta un hook solo cuando Claude usa comandos git en lugar de todos los comandos Bash:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

Si tu hook debe ejecutarse depende de la forma de tu patrón if y del comando Bash que Claude está invocando:

Cuando Claude Code no puede determinar qué comandos ejecuta la entrada Bash, ejecuta tu hook independientemente del patrón. La tabla de coincidencia Bash cubre las formas de comando que Claude Code puede y no puede estrecharse por subcomando. Porque el filtro es mejor esfuerzo, usa el sistema de permisos en lugar de un hook para aplicar un allow o deny duro.

El campo if acepta los mismos patrones que las reglas de permiso: "Bash(git *)", "Edit(*.ts)", y así sucesivamente. Para coincidir con múltiples nombres de herramienta, usa manejadores separados cada uno con su propio valor if, o coincide a nivel de matcher donde se soporta alternancia de tuberías.

if solo funciona en eventos de herramienta: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, y PermissionDenied. Añadirlo a cualquier otro evento evita que el hook se ejecute.

Configura la ubicación del hook

Dónde añadas un hook determina su ámbito:

Ejecuta /hooks en Claude Code para examinar todos los hooks configurados agrupados por evento.

Para desactivar hooks, establece "disableAllHooks": true en tu archivo de configuración. Claude Code lee el valor que queda después de que se aplica la precedencia de configuración, por lo que el archivo de configuración de un proyecto puede anular el tuyo. Los hooks configurados en configuración gestionada aún se ejecutan a menos que disableAllHooks también esté establecido allí. Para el alcance completo de cada nivel, consulta disableAllHooks.

Si editas archivos de configuración directamente mientras Claude Code está ejecutándose, el observador de archivos normalmente recoge cambios de hooks automáticamente.

Hooks basados en prompts

Para decisiones que requieren criterio en lugar de reglas deterministas, usa hooks type: "prompt". En lugar de ejecutar un comando de shell, Claude Code envía tu prompt y los datos de entrada del hook a un modelo Claude (Haiku por defecto) para tomar la decisión. Puedes especificar un modelo diferente con el campo model si necesitas más capacidad.

El único trabajo del modelo es devolver su decisión como JSON:

• "ok": true: la acción procede
• "ok": false: lo que sucede depende del evento:
  • Stop y SubagentStop: la reason se alimenta de vuelta a Claude para que siga trabajando, a menos que la respuesta también establezca "impossible": true para marcar la condición como una que nunca puede ser satisfecha, en cuyo caso Claude Code permite la parada y el turno termina
  • PreToolUse: la llamada de herramienta se deniega; por defecto el turno termina y la reason de denegación aparece en el chat como una línea de advertencia. Establece continueOnBlock: true en el hook para devolver la reason a Claude como el error de la herramienta, para que pueda ajustarse y continuar. Antes de v2.1.210, la reason de denegación se devolvía a Claude como el error de la herramienta y el turno continuaba
  • PostToolUse: por defecto el turno termina y la reason aparece en el chat como una línea de advertencia. Establece continueOnBlock: true para alimentar la reason de vuelta a Claude y continuar el turno en su lugar
  • PostToolBatch, UserPromptSubmit y UserPromptExpansion: el turno termina y la reason aparece en el chat como una línea de advertencia

Este ejemplo usa un hook Stop para preguntarle al modelo si todas las tareas solicitadas están completas. Si el modelo devuelve "ok": false porque la condición aún no se cumple, Claude sigue trabajando y usa la reason como su siguiente instrucción:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

Para opciones de configuración completas, consulta Hooks basados en prompts en la referencia.

Hooks basados en agentes

Cuando la verificación requiere inspeccionar archivos o ejecutar comandos, usa hooks type: "agent". A diferencia de los hooks de prompt que hacen una sola llamada LLM, los hooks de agente generan un subagente que puede leer archivos, buscar código y usar otras herramientas para verificar condiciones antes de devolver una decisión.

Los hooks de agente usan el formato de respuesta "ok" / "reason" con un tiempo de espera predeterminado más largo de 60 segundos y hasta 50 turnos de uso de herramientas. No admiten el campo impossible de los hooks de prompt. En ok: false, Claude Code maneja un hook de agente de la misma manera que maneja un hook de prompt con continueOnBlock: true en el mismo evento, por lo que en PreToolUse y PostToolUse el turno continúa; los hooks de agente no tienen campo continueOnBlock. Consulta configuración de hooks de agente para los campos, incluido el marcador de posición $ARGUMENTS que Claude Code reemplaza con la entrada JSON del hook.

Este ejemplo verifica que las pruebas pasen antes de permitir que Claude se detenga:

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

Usa hooks de prompt cuando los datos de entrada del hook por sí solos son suficientes para tomar una decisión. Usa hooks de agente cuando necesites verificar algo contra el estado real del código base.

Para opciones de configuración completas, consulta Hooks basados en agentes en la referencia.

HTTP hooks

Usa hooks type: "http" para POST de datos de evento a un punto final HTTP en lugar de ejecutar un comando de shell. El punto final recibe el mismo JSON que un hook de comando recibiría en stdin, y devuelve resultados a través del cuerpo de respuesta HTTP usando el mismo formato JSON.

Los HTTP hooks son útiles cuando quieres que un servidor web, función en la nube o servicio externo maneje la lógica del hook: por ejemplo, un servicio de auditoría compartido que registra eventos de uso de herramientas en un equipo.

Este ejemplo publica cada uso de herramienta a un servicio de registro local:

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

El punto final debe devolver un cuerpo de respuesta JSON usando el mismo formato de salida que los hooks de comando. Para bloquear una llamada a herramienta, devuelve una respuesta 2xx con los campos hookSpecificOutput apropiados. Los códigos de estado HTTP por sí solos no pueden bloquear acciones.

Los valores de encabezado soportan interpolación de variables de entorno usando la sintaxis $VAR_NAME o ${VAR_NAME}. Solo las variables listadas en el array allowedEnvVars se resuelven; todas las otras referencias $VAR permanecen vacías.

Para opciones de configuración completas y manejo de respuestas, consulta HTTP hooks en la referencia.

Limitaciones y solución de problemas

Limitaciones

Tenga en cuenta estas restricciones al diseñar hooks:

• Los hooks de comando se comunican solo a través de stdout, stderr y códigos de salida. No pueden activar comandos / o llamadas a herramientas. El texto devuelto a través de additionalContext se inyecta como un recordatorio del sistema que Claude lee como texto plano. Los HTTP hooks se comunican a través del cuerpo de respuesta en su lugar.
• Los tiempos de espera del hook varían según el tipo. Anule por hook con el campo timeout en segundos.
  • command, http, mcp_tool: 10 minutos. Claude Code reduce estos valores predeterminados a 30 segundos para los hooks UserPromptSubmit, PreModelSwitch y PostModelSwitch, y a 10 segundos para MessageDisplay.
  • prompt: 30 segundos.
  • agent: 60 segundos.
  • Los hooks SessionEnd de cualquier tipo comparten un presupuesto de 1,5 segundos. Si su configuración establece un timeout por hook más largo, Claude Code aumenta el presupuesto para que coincida, hasta 60 segundos.
• Los hooks PostToolUse no pueden deshacer acciones ya que la herramienta ya se ha ejecutado.
• Los hooks PermissionRequest se activan cuando Claude Code está a punto de pedirle permiso.
  • En modo no interactivo con la bandera -p, esa solicitud solo existe cuando la devolución de llamada canUseTool del SDK del Agent la proporciona. En ejecuciones simples de -p o con --permission-prompt-tool, use hooks PreToolUse para decisiones de permiso automatizadas en su lugar.
  • Los subagentes de fondo no pueden mostrar una solicitud en modo no interactivo. Claude Code aún ejecuta los hooks para sus llamadas a herramientas, y si ningún hook devuelve una decisión, deniega la llamada. En una sesión interactiva, las solicitudes de subagentes de fondo aparecen en su sesión principal y los hooks se activan como de costumbre.
• Los hooks Stop se activan cada vez que Claude termina de responder, no solo en la finalización de tareas. No se activan en interrupciones del usuario. Los errores de API activan StopFailure en su lugar.
• Cuando múltiples hooks PreToolUse devuelven updatedInput para reescribir los argumentos de una herramienta, el último en terminar gana. Como los hooks se ejecutan en paralelo, el orden es no determinista. Evite tener más de un hook modificando la entrada de la misma herramienta.

Hooks y modos de permiso

Los hooks PreToolUse se activan antes de cualquier verificación de modo de permiso, en cada modo de permiso, incluyendo dontAsk. Un hook que devuelve permissionDecision: "deny" bloquea la herramienta incluso en modo bypassPermissions o con --dangerously-skip-permissions. Esto le permite aplicar política que los usuarios no pueden eludir cambiando su modo de permiso.

Lo inverso no es cierto: un hook que devuelve "allow" no elude reglas de negación de configuración, y no puede suprimir la solicitud de herramientas MCP marcadas requiresUserInteraction o de herramientas conectoras que su organización estableció en ask en sesiones donde esa configuración llega a Claude Code. Los hooks pueden endurecer restricciones pero no relajarlas más allá de lo que las reglas de permiso permiten.

Hook no se activa

El hook está configurado pero nunca se ejecuta.

• Ejecuta /hooks y confirma que el hook aparece bajo el evento correcto
• Verifique que el patrón del matcher coincida exactamente con el nombre de la herramienta. Los matchers distinguen mayúsculas de minúsculas
• Verifique que esté activando el tipo de evento correcto: PreToolUse se activa antes de la ejecución de la herramienta, PostToolUse se activa después. Un hook PermissionRequest se activa cuando Claude Code está a punto de pedirle permiso; consulte las limitaciones para los casos no interactivos

Error de hook en la salida

Ves un mensaje como "PreToolUse hook error: ..." en la transcripción.

• Tu script salió con un código no cero inesperadamente. Pruébalo manualmente canalizando JSON de muestra:

  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?  # Verifica el código de salida
  

• Si ves "command not found", usa rutas absolutas o ${CLAUDE_PROJECT_DIR} para referenciar scripts. Para evitar entrecomillado de shell por completo, añade "args": [] para cambiar a forma exec, que genera el script directamente sin un shell

• Si ves "jq: command not found", instala jq o usa Python/Node.js para análisis JSON

• Si el aviso muestra un mensaje de validación JSON, la salida estándar de su hook se analizó como JSON pero falló la validación del esquema. Si muestra un mensaje de análisis JSON, la salida estándar parecía un objeto JSON pero no era JSON válido. Ambos suceden incluso en salida 0.

  Para corregir una falla de análisis, construya la carga útil con un codificador JSON como jq en lugar de concatenación de cadenas, para que las comillas y barras invertidas dentro de los valores se escapen. La sección Exit code output de la referencia cubre las combinaciones de código de salida y JSON

• Si el script no se ejecuta en absoluto, hazlo ejecutable: chmod +x ./my-hook.sh

`/hooks` no muestra hooks configurados

Editaste un archivo de configuración pero los hooks no aparecen en el menú.

• Las ediciones de archivos normalmente se recogen automáticamente. Si no han aparecido después de unos segundos, el observador de archivos puede haber perdido el cambio: reinicia tu sesión para forzar una recarga.
• Verifique que su JSON sea válido: las comas finales y comentarios no están permitidos
• Confirma que el archivo de configuración está en la ubicación correcta: .claude/settings.json para hooks de proyecto, ~/.claude/settings.json para hooks globales

El hook Stop alcanza el límite de bloqueo

Claude sigue trabajando en lugar de detenerse, luego termina el turno con una advertencia de que el hook Stop bloqueó demasiadas veces consecutivas.

Claude Code anula un hook Stop después de que bloquea ocho veces seguidas sin progreso. Su script de hook necesita verificar si ya activó una continuación. Analice el campo stop_hook_active de la entrada JSON y salga temprano si es true:

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Permite que Claude se detenga
fi
# ... resto de tu lógica de hook

Si tu hook legítimamente necesita más de ocho iteraciones para converger, aumenta el límite con CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.

Hook JSON no tiene efecto

Su hook imprime JSON válido, pero la decisión no surte efecto y no aparece ningún error en la transcripción. Verifique cuál es la causa que se aplica:

• Salida adicional antes del JSON: algo más escribe en stdout primero, generalmente un echo incondicional en su perfil de shell, por lo que la salida ya no comienza con { y Claude Code no la analiza como JSON. La causa y la solución siguen esta lista.
• Un campo en el nivel incorrecto: compare la ubicación de cada campo con el formato JSON output. Por ejemplo, permissionDecision pertenece dentro de hookSpecificOutput, no en el nivel superior.

Cuando Claude Code ejecuta un hook de comando en forma de shell, uno sin args, genera sh -c en macOS y Linux, Git Bash en Windows, o PowerShell cuando Git Bash no está instalado por defecto. Este shell es no interactivo, pero Git Bash y algunas configuraciones, como BASH_ENV apuntando a ~/.bashrc, aún obtienen su perfil. Si ese perfil contiene declaraciones echo incondicionales, la salida se antepone a su JSON del hook:

Shell ready on arm64
{"decision": "block", "reason": "Not allowed"}

La salida combinada ya no comienza con {, por lo que Claude Code trata toda la salida estándar como texto plano e ignora el JSON. En salida 0 nada se reporta en la transcripción; el intento de análisis se registra solo en el registro de depuración. Para corregir esto, envuelva las declaraciones echo en su perfil de shell para que solo se ejecuten en shells interactivos:

# En ~/.zshrc o ~/.bashrc
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

La variable $- contiene banderas de shell, e i significa interactivo. Los hooks se ejecutan en shells no interactivos, por lo que el echo se omite.

Cuando su hook devuelve permissionDecision o additionalContext en el nivel superior en lugar de dentro de hookSpecificOutput, el JSON aún se analiza, y Claude Code ignora los campos mal colocados sin reportar un error. Para ver qué campos ignoró, inicie Claude Code con claude --debug y busque en el registro de depuración Hook JSON output had unrecognized keys.

Técnicas de depuración

Presione Ctrl+O para abrir la vista de transcripción para verificar el resultado de una ejecución de hook:

• Ejecución exitosa: no ve nada, a menos que el JSON del hook muestre algo, como systemMessage o retroalimentación del hook Stop.
  • Para confirmar que un hook se ejecutó, verifique su efecto, como un archivo reformateado, o active el registro de depuración como se describe a continuación y active el hook nuevamente
• Error de bloqueo: en la mayoría de eventos ve la retroalimentación del hook. Cuando el JSON del hook tomó una decisión de bloqueo, la retroalimentación es la razón de esa decisión; de lo contrario es el stderr del hook. En algunos eventos, como ConfigChange y Elicitation, un bloqueo no muestra ningún mensaje.
• Error sin bloqueo: la acción procedió, y ve un aviso <hook name> hook error con una explicación breve, como la primera línea de stderr prefijada con Failed with non-blocking status code:, o un mensaje de validación o análisis JSON.

Qué combinaciones de código de salida y JSON producen cada resultado, incluyendo las excepciones por evento, se define en la sección Exit code output de la referencia.

Para detalles de ejecución completos incluyendo qué hooks coincidieron, sus códigos de salida, stdout y stderr, lee el registro de depuración. Inicia Claude Code con claude --debug-file /tmp/claude.log para escribir en una ruta conocida, luego tail -f /tmp/claude.log en otra terminal. Si iniciaste sin esa bandera, ejecuta /debug a mitad de sesión para habilitar el registro y encontrar la ruta del registro.

Aprende más

• Referencia de Hooks: esquemas de eventos completos, formato de salida JSON, hooks asincronos y hooks de herramientas MCP
• Consideraciones de seguridad: revisa antes de desplegar hooks en entornos compartidos o de producción
• Ejemplo de validador de comandos Bash: implementación de referencia completa