Cargando
Cargando

Hooks

ResumenTranscripción

Los hooks te permiten ejecutar comandos en puntos específicos del ciclo de vida de Claude Code. La diferencia clave entre los hooks y todo lo demás que se cubre en este curso es que los hooks son deterministas: siempre se ejecutan.

Por qué usar hooks

Puedes indicarle a Claude en tu CLAUDE.md que ejecute Prettier después de cada edición de archivo. La mayoría de las veces lo hará. Pero a veces no. Un hook hace que ocurra cada vez, sin excepciones.

Los casos de uso comunes incluyen:

  • Formateo automático después de ediciones de archivos
  • Registro de todos los comandos ejecutados para fines de cumplimiento
  • Bloqueo de operaciones peligrosas como modificar archivos de producción
  • Enviarte notificaciones cuando Claude termina una tarea

Cómo funcionan

Los hooks se configuran en tu settings.json. Eliges un evento, opcionalmente estableces un matcher para indicar a qué herramientas se aplica, y proporcionas un comando para ejecutar. Algunos de los eventos más comunes son:

  • PreToolUse — se ejecuta antes de una llamada a una herramienta
  • PostToolUse — se ejecuta después de que se completa una llamada a una herramienta
  • UserPromptSubmit — se ejecuta cuando envías un prompt, antes de que Claude lo procese
  • Stop — se ejecuta cuando Claude termina de responder
  • Notification — se ejecuta cuando Claude envía una notificación

Estos son solo algunos de los eventos a los que puedes engancharte (hook); Claude Code admite muchos más. Consulta la referencia de hooks para ver la lista completa.

Los configuras editando directamente settings.json. El comando /hooks dentro de Claude Code abre una lista de solo lectura de tus hooks configurados, para que puedas comprobar que uno nuevo aparece.

El archivo settings.json dentro del directorio .claude con configuración de hooks

Un ejemplo práctico

El hook más común: formateo automático después de ediciones. Configura un hook PostToolUse con un matcher de "Edit|Write" para que se active después de que Claude use la herramienta Edit o Write. El comando ejecuta el formateador que use tu proyecto. Para Prettier, agrega esto a .claude/settings.json (necesita jq):

json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "file=$(jq -r '.tool_input.file_path') && npx prettier --write -- \"$file\""
          }
        ]
      }
    ]
  }
}

Para probarlo, pídele a Claude que edite un archivo y luego comprueba que el archivo se reformateó.

Bloqueo con PreToolUse

Los hooks PreToolUse pueden bloquear llamadas a herramientas antes de que se ejecuten. Tu hook recibe el nombre de la herramienta y la entrada como JSON en stdin. El código de salida determina el comportamiento:

  • Código de salida 0 — proceder con normalidad.
  • Código de salida 2 — bloquear la acción. El mensaje de stderr se envía de vuelta a Claude como retroalimentación para que sepa por qué fue bloqueado y pueda ajustarse.
  • Cualquier otro código de salida — un error no bloqueante que se te muestra pero no detiene nada.

Así es como se aplican reglas estrictas. Bloquea escrituras a un directorio de configuración de producción. Bloquea comandos de bash que contengan rm -rf. Bloquea commits a main. Lo que sea que tu equipo necesite que esté garantizado, no sugerido.

Un archivo settings.json que muestra hooks PreToolUse y PostToolUse con matchers y comandos

Compartir hooks con tu equipo

Los hooks configurados en .claude/settings.json son a nivel de proyecto y se pueden incluir en tu repositorio. Esto significa que todo tu equipo obtiene los mismos hooks automáticamente. Usa la variable de entorno CLAUDE_PROJECT_DIR en tus comandos para hacer referencia a scripts almacenados en tu proyecto, de modo que funcionen sin importar cuál sea el directorio de trabajo actual de Claude.

Resumen

Los hooks te dan control determinista sobre el comportamiento de Claude Code. Usa PostToolUse para el formateo automático y el registro. Usa PreToolUse para bloquear operaciones peligrosas. Configúralos en settings.json y visualízalos con /hooks. Y agrégalos a tu repositorio para que tu equipo también los tenga.

Si algo necesita ocurrir siempre sin falta, no lo pongas en un prompt. Ponlo en un hook.