Tutorial de hooks de Claude Code: 5 hooks de producción desde cero

Claude Code ejecuta la acción correcta en la inmensa mayoría de los casos. Los casos límite que quedan incluyen hacer force-push a main, saltarse tu formateador y confirmar código que no pasa el lint. Los hooks eliminan esos casos límite al añadir barreras deterministas en 31 puntos del ciclo de vida del flujo de trabajo de Claude (a agosto de 2026).¹ Este tutorial forma parte de mi serie sobre AI engineering dedicada a construir sistemas de agentes de nivel producción. Se disparan siempre, sin excepción, sin importar cómo esté redactado el prompt ni cómo se comporte el modelo.

TL;DR: los hooks son comandos de shell que se disparan con los eventos del ciclo de vida de Claude Code.¹ Los hooks PreToolUse inspeccionan y bloquean acciones (código de salida 2 = bloquear, código 0 = permitir).² Los hooks PostToolUse validan y formatean después del hecho. Se configuran en .claude/settings.json con un matcher (un nombre de herramienta exacto, una lista separada por | o una expresión regular) y un arreglo hooks anidado.³ El tutorial de abajo construye cinco hooks de producción: formateador automático, barrera de seguridad, ejecución de pruebas, alerta de notificación y control de calidad antes del commit.

Puntos clave

• Desarrolladores en solitario: empieza por el formateador automático (hook 1) y la barrera de seguridad (hook 2). Estos dos hooks evitan los errores más habituales de Claude Code sin ningún mantenimiento posterior.
• Líderes de equipo: versiona los hooks en el .claude/settings.json de tu repositorio. Cada integrante del equipo obtiene automáticamente las mismas barreras de seguridad y los mismos controles de calidad.
• Ingenieros de seguridad: el código de salida 2 bloquea la acción.² El código de salida 1 solo registra una advertencia. Todo hook de seguridad PreToolUse debe usar exit 2 o no impone nada.

¿Qué son los hooks?

Los hooks son comandos de shell que se ejecutan en eventos concretos del ciclo de vida de una sesión de Claude Code. Corren fuera del LLM, como simples scripts disparados por las acciones de Claude, no como prompts que el modelo interpreta.

Cuatro categorías principales cubren los usos más habituales (Claude Code documenta 31 tipos de evento a agosto de 2026):¹

• Eventos de sesión: SessionStart se dispara cuando comienza una sesión, SessionEnd cuando se cierra y Stop cada vez que Claude termina una respuesta (no solo al final de la sesión). Úsalos para preparación, limpieza y notificaciones.
• Eventos de herramienta: PreToolUse y PostToolUse se disparan antes y después de que Claude use una herramienta (escribir un archivo, ejecutar un comando de bash o buscar en el código). Son los hooks más potentes porque pueden inspeccionar y bloquear acciones concretas.
• Eventos de notificación: Notification se dispara cuando Claude genera una notificación. Resulta útil para enrutar avisos a Slack, a las notificaciones del escritorio o a sistemas de registro.
• Eventos de subagente: SubagentStop se dispara cuando un subagente (lanzado con la herramienta Agent) termina.⁴ Los hooks también se disparan con las acciones de los subagentes, así que tus barreras de seguridad se aplican de forma recursiva.

La semántica de los códigos de salida importa.² El código 0 significa éxito (continuar). El código 2 significa bloquear la acción. El código 1 es un error de hook no bloqueante en el que la acción se ejecuta igualmente. Todo hook crítico para la seguridad debe usar exit 2 para que su barrera funcione de verdad.

El modelo mental: tres tipos de garantías

Antes de escribir un hook, pregúntate: ¿qué clase de garantía necesito?

Las garantías de formato aseguran la coherencia después del hecho. Los hooks PostToolUse sobre Write/Edit ejecutan tu formateador tras cada cambio de archivo. Lo que produzca el modelo da igual, porque el formateador lo normaliza todo. Estos hooks son idempotentes y se pueden ejecutar sin riesgo en cada edición.

Las garantías de seguridad impiden acciones peligrosas antes de que se ejecuten. Los hooks PreToolUse sobre Bash inspeccionan los comandos y bloquean los patrones destructivos con el código de salida 2. Estos hooks deben ser rápidos (menos de 500 ms) porque filtran cada llamada de herramienta que coincida, y deben usar el código 2 (no el 1), porque el código 1 solo advierte sin bloquear.

Las garantías de calidad validan el estado en puntos de decisión. Los hooks PreToolUse sobre los comandos git commit ejecutan tu linter o tu suite de pruebas y bloquean el commit si los controles de calidad fallan. A diferencia de los hooks de formato, que se disparan en cada edición, los de calidad solo actúan en momentos concretos, con lo que la sobrecarga se mantiene baja.

El antepasado conceptual son los hooks de Git⁸: pre-commit, pre-push y post-commit cumplen esos mismos tres papeles. Los hooks de Claude Code extienden el patrón desde las operaciones de Git hasta cada acción de herramienta que emprende el agente. Diseco esa evolución en every hook is a scar: cada hook existe porque algo salió mal sin él.

Fundamentos de la configuración de hooks

Los hooks viven en tus archivos de configuración:

• A nivel de proyecto: .claude/settings.json en la raíz de tu repositorio (compartido con tu equipo)³
• A nivel de usuario: ~/.claude/settings.json (tus hooks personales, aplicados de forma global)³

La estructura JSON:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/your/script.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/another-script.sh"
          }
        ]
      }
    ]
  }
}

Cada entrada tiene un matcher que filtra nombres de herramienta como Bash, Write, Edit, Read, Glob, Grep o Agent, y un arreglo hooks con definiciones de hook. La semántica del matcher según la referencia: "*", "" o un matcher omitido coinciden con todo; un valor formado por letras, dígitos, _, -, |, comas y espacios es un nombre exacto o una lista, así que Write|Edit coincide con ambas herramientas (el guion bajo importa en los nombres de herramientas MCP como mcp__github__search_code); cualquier otra cosa se trata como una expresión regular sin anclar. La coincidencia distingue mayúsculas de minúsculas – bash nunca coincide con Bash. Cada hook indica un type ("command" para comandos de shell) y el command que se debe ejecutar.

Puedes revisar los hooks registrados con el navegador de solo lectura /hooks dentro de una sesión; para añadir, cambiar o eliminar hooks, edita directamente el JSON de configuración.⁵

Cuando un hook se dispara, Claude Code entrega el contexto como un objeto JSON por stdin: el nombre de la herramienta, la entrada de la herramienta (incluido file_path en las operaciones sobre archivos) y los metadatos de la sesión.⁶ Tu script lee stdin – normalmente con jq – para decidir. También se definen algunas variables de entorno con contexto – $CLAUDE_PROJECT_DIR para resolver rutas, $CLAUDE_EFFORT para el nivel de esfuerzo actual –, pero los campos propios de cada herramienta, como la ruta del archivo, llegan solo por stdin; no existe ninguna variable $FILE_PATH por herramienta.

5 hooks prácticos

Cada hook de abajo resuelve un problema real que encontré usando Claude Code como mi herramienta principal de desarrollo. Todos los ejemplos usan el esquema anidado correcto de la referencia de hooks⁷.

1. Formateo automático al editar un archivo

Claude escribe código funcionalmente correcto que de vez en cuando rompe las reglas de formato de tu proyecto. Al principio probé a añadir «ejecuta siempre black después de editar archivos de Python» a mi CLAUDE.md, pero la instrucción funcionaba solo alrededor del 80 % de las veces. A veces el modelo se saltaba el paso de formateo cuando estaba concentrado en un cambio complejo con varios archivos. Un hook PostToolUse elimina esa inconsistencia por completo: tu formateador se ejecuta tras cada escritura de archivo, sin importar qué decidiera hacer el modelo.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'FILE=$(jq -r \".tool_input.file_path // empty\"); if [[ \"$FILE\" == *.py ]]; then black --quiet \"$FILE\" 2>/dev/null; elif [[ \"$FILE\" == *.js || \"$FILE\" == *.ts ]]; then npx prettier --write \"$FILE\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

El hook lee la entrada JSON de la herramienta desde stdin y extrae .tool_input.file_path con jq – ese objeto de stdin es el único lugar donde existe la ruta del archivo, ya que Claude Code no define variables de entorno por herramienta. Después comprueba la extensión y ejecuta el formateador adecuado: los archivos de Python reciben black, y los de JavaScript y TypeScript, prettier. El 2>/dev/null suprime la salida ruidosa para que solo veas errores reales.

En proyectos más grandes, mueve el comando en línea a un script independiente por legibilidad.

2. Barrera de seguridad para comandos peligrosos

Los hooks PreToolUse sobre la herramienta Bash inspeccionan el comando que Claude está a punto de ejecutar y lo bloquean si coincide con un patrón peligroso. Escribí la primera versión de este hook después de que Claude hiciera un force-push a main durante una sesión de refactorización. (Exploro las implicaciones más amplias de la autonomía de los agentes en anatomy of a claw y Claude Code as infrastructure.) Al modelo se le había pedido que «subiera los cambios» y lo interpretó como git push --force origin main porque la rama había divergido. El arreglo llevó segundos; el incidente motivó una barrera permanente.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r \".tool_input.command\"); if echo \"$CMD\" | grep -qE \"rm\\s+-rf\\s+/|git\\s+push\\s+(-f|--force)\\s+(origin\\s+)?main|git\\s+reset\\s+--hard|DROP\\s+TABLE|:\\(\\)\\s*\\{\\s*:\"; then echo \"BLOCKED: Dangerous command detected: $CMD\" >&2; exit 2; fi'"
          }
        ]
      }
    ]
  }
}

Cuando este hook termina con el código 2, Claude Code cancela el comando pendiente. El mensaje de error se imprime tanto en tu terminal como en el contexto de Claude, así que el modelo entiende por qué falló la acción y propone una alternativa más segura.

Patrones bloqueados: - rm -rf / (borrado recursivo desde la raíz) - git push --force main y git push -f main (force-push a la rama main) - git reset --hard (destrucción de trabajo sin confirmar) - DROP TABLE (destrucción accidental de la base de datos) - Fork bombs (el patrón detecta el arranque :(){, lo que cubre las variantes con y sin espacios)

Adapta esta lista a tu entorno. Las bases de datos de producción exigen patrones de SQL destructivo. Los despliegues basados en CLI exigen guardianes para los comandos de despliegue.

3. Ejecutar pruebas después de cada cambio

Cuando Claude edita un archivo de Python, ejecuta automáticamente las pruebas correspondientes. Ejecutarlas de inmediato detecta regresiones antes de que se acumulen a lo largo de tres o cuatro ediciones posteriores.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'FILE=$(jq -r \".tool_input.file_path // empty\"); if [[ \"$FILE\" == *.py && \"$FILE\" != *test_* ]]; then TEST_FILE=\"tests/test_$(basename \"$FILE\")\"; if [[ -f \"$TEST_FILE\" ]]; then if ! OUT=$(python -m pytest \"$TEST_FILE\" -x --tb=short 2>&1); then echo \"TESTS FAILED after editing $FILE:\" >&2; echo \"$OUT\" | tail -20 >&2; exit 2; fi; fi; fi'"
          }
        ]
      }
    ]
  }
}

El hook extrae del JSON de stdin la ruta del archivo editado, comprueba si se trata de un archivo fuente de Python (y no de un archivo de pruebas), busca el archivo de pruebas correspondiente según la convención de nombres con prefijo test_ y lo ejecuta si lo encuentra. La opción -x se detiene en el primer fallo y tail -20 mantiene la salida breve. Lo que hace útil al hook es el exit 2 ante un fallo: un hook PostToolUse no puede deshacer la edición que ya ocurrió, pero el código 2 entrega a Claude por stderr la salida de las pruebas fallidas, y entonces repara la rotura antes de seguir. Una versión que se limita a imprimir el fallo con código 0 lo manda al registro de depuración, donde nadie mira.

Nota: el hook de arriba asume un directorio tests/ plano con nombres que empiezan por test_. En proyectos que reflejan el árbol de fuentes (por ejemplo, tests/api/test_users.py para src/api/users.py), reemplaza la línea TEST_FILE por:

TEST_FILE="tests/$(echo "$FILE" | sed 's|.*/src/||; s|\([^/]*\)\.py$|test_\1.py|')"

El hook de ejecución de pruebas resulta especialmente valioso en las sesiones de refactorización en las que Claude toca varios archivos. Sin retroalimentación inmediata los errores se acumulan: Claude edita el archivo A, rompe las pruebas del archivo B y luego edita el archivo C partiendo del estado roto de B. Para cuando descubres el fallo hay tres archivos que arreglar en lugar de uno. Ejecutar las pruebas tras cada edición detecta la primera rotura al instante.

4. Notificación cuando Claude termina

Los turnos largos de Claude Code pueden tardar minutos. En lugar de vigilar la terminal, recibe una notificación cuando Claude termine de responder. (Stop se dispara al final de cada respuesta; para un hook en el cierre real de la sesión, registra SessionEnd.)

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude finished responding\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

La variante de macOS de arriba usa osascript para lanzar una notificación nativa. En Linux, sustituye la línea de osascript por notify-send "Claude Code" "Finished responding". Para notificaciones de Slack, usa un webhook:

curl -s -X POST "$SLACK_WEBHOOK_URL" \
  -H 'Content-type: application/json' \
  -d '{"text": "Claude Code finished responding"}'

Yo uso la variante de Slack para las tareas en segundo plano lanzadas con & <task> (el modo en segundo plano de Claude Code). La notificación de escritorio cubre las sesiones interactivas.

5. Control de calidad antes del commit

Antes de que Claude ejecute git commit, valida que el código pase el linter. Una barrera de lint previa al commit detecta problemas que el formateo por sí solo pasa por alto: imports sin usar, variables no definidas, errores de tipos.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r \".tool_input.command\"); if echo \"$CMD\" | grep -qE \"^git\\s+commit\"; then if ! LINT_OUTPUT=$(ruff check . --select E,F,W 2>&1); then echo \"LINT FAILED -- fix before committing:\" >&2; echo \"$LINT_OUTPUT\" >&2; exit 2; fi; fi'"
          }
        ]
      }
    ]
  }
}

La barrera de calidad se activa solo cuando el comando de Bash empieza por git commit. Ejecuta ruff (un linter de Python muy rápido) con las reglas de error, pyflakes y advertencia. Si hay algún problema, el hook bloquea el commit (código 2) y Claude ve la salida del linter, lo que normalmente lo lleva a corregir los problemas y reintentar.

Puedes apilar varios controles de calidad: mypy para la comprobación de tipos, bandit para el análisis de seguridad o los scripts de validación propios de tu proyecto. Los hooks PreToolUse sobre comandos de Bash te dan una barrera programable antes de cualquier acción de shell.

PreToolUse y PostToolUse en .claude/settings.json: la referencia

Si buscabas la forma de la configuración de PreToolUse/PostToolUse y llegaste aquí, esta es la versión compacta. Ambos eventos se anidan bajo la clave hooks de .claude/settings.json (proyecto) o de ~/.claude/settings.json (usuario); los ámbitos se combinan y los manejadores idénticos se deduplican. Un bloque que conecta ambos eventos:³

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".claude/hooks/guard.sh" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": ".claude/hooks/format.sh" }]
      }
    ]
  }
}

El contrato en tres líneas: ambos eventos entregan el JSON de la herramienta por stdin (.tool_input.command para Bash, .tool_input.file_path para Write/Edit; no hay ninguna variable de entorno por herramienta).⁶ PreToolUse se dispara antes de la llamada a la herramienta y puede bloquearla con el código 2. PostToolUse se dispara después de que la herramienta tenga éxito – no puede deshacer la acción, pero el código 2 devuelve su stderr a Claude, que entonces arregla lo que el hook señaló.²

Para la documentación completa de ambos eventos – campos de salida JSON, permissionDecision, updatedInput, tiempos de espera – la referencia oficial es code.claude.com/docs/en/hooks; la sección de hooks de mi guía de Claude Code cubre el mismo terreno con patrones probados en el campo.

¿Adivinaste el nombre de un evento? La correspondencia

Eventos de hook que la gente busca frente a lo que Claude Code dispara realmente:¹

En total existen treinta y un eventos: la tabla de eventos de la guía los enumera todos.

Un hook PreToolUse, PostToolUse y Stop en una sola configuración

Los tres eventos más buscados, conectados entre sí – un guardián de comandos, un formateador y una notificación de finalización:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".claude/hooks/guard-bash.sh" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "bash -c 'FILE=$(jq -r \".tool_input.file_path // empty\"); [[ \"$FILE\" == *.py ]] && black --quiet \"$FILE\" || true'" }]
      }
    ],
    "Stop": [
      {
        "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude finished responding\" with title \"Claude Code\"'" }]
      }
    ]
  }
}

guard-bash.sh es la barrera de seguridad del hook 2 trasladada a un script independiente: guarda el cuerpo del comando de una línea bash -c del hook 2 (todo lo que hay entre las comillas simples exteriores) como .claude/hooks/guard-bash.sh, añade un shebang #!/bin/bash y hazlo ejecutable con chmod +x; o toma el script ya hecho con el mismo nombre de Claude Code Hooks Explained. Cada evento conserva su propia semántica: el guardián PreToolUse puede vetar comandos (código 2), el formateador PostToolUse se ejecuta tras cada edición que coincida y el hook Stop se dispara al final de cada respuesta, sin necesidad de matcher: Stop no es un evento de herramienta, así que no hay nada que filtrar.¹

Consejos para depurar hooks

Los hooks fallan en silencio más a menudo de lo que cabría esperar. Cinco técnicas que uso para depurarlos:

1. Prueba primero los scripts por separado. Canaliza a mano un JSON de ejemplo hacia tu script: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh. Si falla fuera de Claude Code, también fallará dentro.
2. Ten claro adónde va realmente stderr. Stderr llega al contexto de Claude solo cuando el hook termina con 2; con el código 0 acaba en el registro de depuración, y con otros códigos distintos de cero solo aparece un aviso de error de hook en la transcripción. Mientras desarrollas, ejecuta claude --debug (o /debug a mitad de sesión) y vigila el registro de depuración, donde acaba la salida de los hooks que terminan con 0.
3. Vigila los fallos de jq. Si tu ruta JSON es incorrecta, jq⁹ devuelve null en silencio y tus condicionales nunca coincidirán. Prueba tus expresiones de jq contra entradas de herramienta reales.
4. Verifica los códigos de salida. El código 2 bloquea acciones. El código 1 solo advierte. Un hook PreToolUse que usa exit 1 por accidente no impone nada mientras aparenta funcionar. Empieza con una postura permisiva (código 0 por defecto) y reserva exit 2 para patrones concretos que quieras bloquear.
5. Mantén los hooks rápidos. Los hooks se ejecutan de forma síncrona. Un hook que tarda 5 segundos añade 5 segundos a cada uso de herramienta que coincida. Mantengo todos mis hooks por debajo de 2 segundos, idealmente por debajo de 500 milisegundos.

El error más común con los hooks: escribir una barrera de seguridad con exit 1 en lugar de exit 2. El hook parece funcionar durante las pruebas porque el mensaje de advertencia se imprime en la terminal. Pero el código 1 es una advertencia no bloqueante. El comando peligroso se ejecuta igualmente. He visto este error en las configuraciones de hooks de tres equipos distintos, cada uno convencido de haber bloqueado los force-push. Prueba cada hook de seguridad disparando el patrón bloqueado y comprobando que la acción se impidió de verdad, no que solo se advirtió de ella.

Próximos pasos

Estos cinco hooks cubren lo fundamental: formateo, seguridad, pruebas, notificaciones y barreras de calidad. Cuando estos patrones te resulten cómodos, puedes construir hooks para inyección de contexto (añadir instrucciones propias del proyecto al iniciar la sesión), guardianes de recursión (evitar bucles infinitos de subagentes) y orquestación de flujos de trabajo (encadenar procesos de varios pasos).

Para la arquitectura de los hooks, el ciclo de vida completo de 31 eventos y patrones avanzados, consulta la sección de hooks de mi Claude Code guide completa, o el recorrido evento por evento de Claude Code Hooks Explained.

También escribí sobre el origen de mis 95 hooks de producción en Claude Code Hooks: Why Each of My 95 Hooks Exists, que repasa los incidentes que motivaron cada uno.

Referencias

FAQ

¿Pueden los hooks impedir que Claude Code ejecute un comando?

Sí. Los hooks PreToolUse bloquean cualquier acción de herramienta terminando con el código 2. Claude Code cancela la acción pendiente y le muestra al modelo la salida de stderr del hook. El código 1 es un error de hook no bloqueante en el que la acción sigue adelante. La distinción entre códigos importa: todo hook de seguridad debe usar exit 2, no exit 1.² Claude ve el motivo del rechazo y propone una alternativa más segura.

¿Dónde pongo los archivos de configuración de los hooks?

Las configuraciones de hooks van en .claude/settings.json para los hooks a nivel de proyecto (versionados en tu repositorio, compartidos con tu equipo) o en ~/.claude/settings.json para los hooks a nivel de usuario (personales, aplicados a todos los proyectos). Cuando existen ambos, los hooks se combinan en lugar de sobrescribirse: se ejecuta cada hook coincidente de cada ámbito y los manejadores idénticos se deduplican. Recomiendo usar rutas absolutas para los archivos de script y evitar así problemas con el directorio de trabajo.

¿Los hooks funcionan con subagentes?

Sí. Los hooks también se disparan con las acciones de los subagentes.⁴ Si Claude lanza un subagente con la herramienta Agent, tus hooks PreToolUse y PostToolUse se ejecutan para cada herramienta que use ese subagente. Sin aplicación recursiva de los hooks, un subagente podría saltarse tus barreras de seguridad. El evento SubagentStop te permite ejecutar tareas de limpieza o validación cuando un subagente completa su trabajo.⁴

¿Cuántos hooks son demasiados?

El límite lo pone el rendimiento, no la cantidad. Cada hook se ejecuta de forma síncrona, así que el tiempo total de ejecución se suma a cada llamada de herramienta que coincida. Tengo 95 hooks repartidos entre la configuración de usuario y la de proyecto sin latencia perceptible, porque cada uno termina en menos de 200 ms. El umbral que vigilo: si un hook PostToolUse añade más de 500 ms a cada edición de archivo, la sesión se siente pesada. Mide tus hooks con time antes de desplegarlos. Diez hooks rápidos rinden más que dos lentos.