Hooks de Claude Code en 2026: una guía práctica paso a paso

Los hooks de Claude Code son comandos de shell, llamadas HTTP o prompts de LLM definidos por el usuario que se ejecutan automáticamente en puntos fijos del ciclo de vida de Claude Code: antes de que se ejecute una herramienta, después de editar un archivo, cuando comienza una sesión o cuando Claude termina un turno. Existen para hacer que ciertas acciones sean deterministas. En lugar de confiar en que el modelo recuerde formatear tu código o evitar un comando destructivo, un hook impone la regla siempre. Esta guía cubre qué son los hooks de Claude Code, los eventos con los que se disparan, cómo configurar el primero, un ejemplo funcional que puedes copiar y cuándo recurrir a un hook en lugar de a un skill o un subagente.

Ejecutamos el pipeline de contenidos de este sitio sobre Claude Code, así que los hooks forman parte de nuestro conjunto de herramientas diario. Los patrones siguientes son los que conviene aprender primero.

¿Qué son los hooks de Claude Code?

Un hook es una regla impuesta por código en lugar de por instrucciones. Todo lo que pongas en un archivo CLAUDE.md o en un prompt es una sugerencia que el modelo puede, en principio, ignorar u olvidar. Un hook no es opcional: cuando el evento se dispara, el hook se ejecuta, y punto. Según la documentación de hooks de Anthropic, un hook es «un comando de shell, endpoint HTTP o prompt de LLM definido por el usuario que se ejecuta automáticamente en puntos concretos del ciclo de vida de Claude Code».

Esa distinción es lo esencial. Si quieres que tu linter se ejecute después de cada edición, un prompt que diga «ejecuta siempre el linter» funciona la mayoría de las veces; un hook PostToolUse lo ejecuta cada vez, sin depender del criterio del modelo. Los hooks son la forma de convertir «Claude normalmente hace X» en «Claude siempre hace X». Entre las tareas habituales están formatear archivos automáticamente, bloquear comandos de shell arriesgados, enviar una notificación de escritorio cuando Claude necesita una entrada e inyectar contexto fresco (como la rama actual de git) al inicio de una sesión.

Cuándo se disparan los hooks: los eventos del ciclo de vida

Claude Code expone más de treinta eventos del ciclo de vida a los que puedes engancharte, pero un puñado cubre casi todos los casos de uso reales. Cada evento pasa a tu hook una carga JSON por stdin que describe lo que está ocurriendo.

Evento	Se dispara cuando	Uso típico
UserPromptSubmit	Envías un prompt, antes de que Claude lo lea	Inyectar contexto, bloquear secretos en un prompt
PreToolUse	Antes de que se ejecute cualquier herramienta	Bloquear o filtrar un comando; puede denegar la acción
PostToolUse	Después de que una herramienta tiene éxito	Formatear código, ejecutar tests, aplicar el linter
SessionStart	Una sesión comienza o se reanuda	Cargar contexto de rama, ticket o entorno
Stop	Claude termina de responder	Imponer «los tests deben pasar antes de que pares»
SubagentStop	Un subagente termina	Validar la salida de un subagente
Notification	Claude envía una notificación	Alertas de escritorio cuando se necesita una entrada

Los dos que usarás más son PreToolUse (para impedir que las cosas ocurran) y PostToolUse (para reaccionar después de que ocurren). Un campo matcher permite que cada hook apunte a herramientas concretas, de modo que un formateador puede dispararse solo con Edit y Write, mientras que un guardián de comandos se dispara solo con Bash.

Cómo configurar tu primer hook

Los hooks viven en un bloque hooks dentro de un archivo de configuración. Dónde coloques ese archivo decide su alcance:

Archivo	Alcance	Compartible
~/.claude/settings.json	Todos los proyectos de tu máquina	No
.claude/settings.json	Un proyecto	Sí, súbelo al repositorio
.claude/settings.local.json	Un proyecto, privado	No, excluido por gitignore

La estructura anida tres niveles: el evento, un grupo matcher que filtra a qué herramientas se aplica y el handler que hace el trabajo de verdad. Aquí tienes el hook de notificación de escritorio de la guía de configuración de Anthropic, que te avisa cada vez que Claude está esperándote:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "notify-send 'Claude Code' 'Waiting for your input'" }
        ]
      }
    ]
  }
}

Añádelo a .claude/settings.json, reinicia la sesión y el hook estará activo. Un matcher vacío significa «coincide con todo». Ese es todo el modelo mental: elige un evento, acótalo opcionalmente con un matcher y apúntalo a un comando.

Un ejemplo funcional: formatear ediciones y bloquear comandos arriesgados

Dos hooks se ganan su sitio en casi cualquier proyecto. El primero formatea cada archivo que Claude toca; el segundo se niega a ejecutar comandos de shell destructivos.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "prettier --write \"$CLAUDE_FILE_PATHS\" 2>/dev/null || true" }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh" }
        ]
      }
    ]
  }
}

El guardián PreToolUse es un pequeño script que lee el comando propuesto y decide si lo permite. Aquí es donde importan los códigos de salida: salir con 0 significa «sin objeciones, adelante», mientras que salir con 2 es un error de bloqueo que detiene la herramienta y devuelve tu mensaje a Claude. También puedes imprimir JSON estructurado para un control más fino:

#!/bin/bash
# .claude/hooks/block-rm.sh
COMMAND=$(jq -r '.tool_input.command')
if echo "$COMMAND" | grep -qE 'rm -rf|:(){:|:&};:'; then
  jq -n '{ hookSpecificOutput: {
    hookEventName: "PreToolUse",
    permissionDecision: "deny",
    permissionDecisionReason: "Destructive command blocked by project hook"
  }}'
  exit 0
fi
exit 0

Ahora Claude no puede, físicamente, ejecutar rm -rf en este proyecto, y cada archivo editado sale formateado, sin que ninguno de los dos comportamientos dependa de que el modelo se acuerde de hacerlo.

Hooks basados en prompt y en agente (nuevos en 2026)

No toda regla es un sí/no limpio que puedas expresar en un script de shell. Anthropic añadió dos tipos de hook en 2026 para decisiones que requieren criterio. Un hook basado en prompt (type: "prompt") envía la entrada del hook a un modelo de Claude, Haiku por defecto, y deja que el modelo devuelva la decisión, útil para algo como «bloquea este mensaje de commit si filtra el nombre de un cliente». Un hook basado en agente (type: "agent") genera un subagente para verificar algo más complejo antes de que Claude continúe. Ambos cambian el determinismo de un comando de shell por flexibilidad, y ambos cuestan una llamada al modelo, así que resérvalos para los casos que una regex realmente no pueda manejar. Para la gran mayoría de los hooks, un simple command es más rápido, gratuito y totalmente predecible.

Hooks frente a skills, subagentes y CLAUDE.md

Claude Code te ofrece varios puntos de extensión, y el error común es usar el equivocado. La línea divisoria es el determinismo.

• Hooks imponen una regla con código. Úsalos cuando algo deba ocurrir siempre, independientemente de lo que decida el modelo: formateo, salvaguardas, notificaciones, inyección de contexto.
• Skills dan a Claude instrucciones y scripts reutilizables que elige aplicar cuando una situación encaja. Amplían la capacidad, no la imposición.
• Subagentes ejecutan trabajo en un contexto aislado para que una tarea grande no inunde el hilo principal. Tienen que ver con el contexto, no con las reglas.
• CLAUDE.md es una guía persistente que el modelo lee y normalmente sigue, pero puede anular.

Si tu instrucción se ignora una y otra vez, esa es la señal para ascenderla de una línea de CLAUDE.md a un hook. Los hooks también encajan de forma natural con los servidores MCP: un hook puede llamar a una herramienta MCP, o dispararse con el uso de una herramienta MCP, para conectar a Claude con tus sistemas existentes.

¿Es seguro? Los hooks se ejecutan con todos tus permisos

Sí, con una salvedad seria: los hooks ejecutan comandos arbitrarios en tu máquina con los permisos de tu usuario, automáticamente y sin una petición de confirmación. La guía de Anthropic es tajante en que eres el único responsable de lo que hacen tus hooks, y en que un hook descuidado puede borrar archivos o corromper datos. Nunca pegues una configuración de hook de una fuente no confiable sin leer antes cada comando, mantén los hooks compartidos en un .claude/settings.json versionado para que tus compañeros puedan revisarlos y prefiere los guardianes de bloqueo frente a cualquier cosa que escriba o borre por su cuenta. Trata a un hook como tratarías cualquier script que se ejecuta sin supervisión.

Preguntas frecuentes

¿Para qué puedes usar los hooks de Claude Code?

Los usos más comunes son el formateo y el linting automáticos tras las ediciones, el bloqueo de comandos peligrosos o fuera de política, la ejecución de tests antes de que Claude termine un turno, el envío de notificaciones de escritorio cuando Claude necesita una entrada y la inyección de contexto (rama de git, número de ticket, entorno) al inicio de la sesión.

¿Cuál es la diferencia entre un hook y una regla de CLAUDE.md?

Una regla de CLAUDE.md es una guía que el modelo lee y normalmente sigue, pero que puede ignorar u olvidar. Un hook lo impone el código y se ejecuta cada vez que su evento se dispara. Usa CLAUDE.md para preferencias y hooks para todo lo que deba estar garantizado.

¿Cuántos eventos de hook hay y dónde está la lista completa?

Claude Code expone más de treinta eventos del ciclo de vida, desde SessionStart hasta PreToolUse, PostToolUse, Stop y los eventos de subagente. La lista completa y actual, con los esquemas de entrada y salida, está en la referencia de hooks oficial.

¿Los hooks ralentizan Claude Code?

Los hooks de comando suelen ser rápidos y todos los hooks que coinciden se ejecutan en paralelo, así que la sobrecarga es pequeña. Los hooks basados en prompt y en agente añaden una llamada al modelo y son más lentos, así que resérvalos para decisiones que un script de shell no pueda tomar.

Fuentes

• Claude Code Docs — Referencia de hooks: lista oficial de eventos del ciclo de vida, estructura de configuración, matchers, esquema de entrada, códigos de salida y campos de salida JSON.
• Claude Code Docs — Automatiza acciones con hooks (guía): recorrido del primer hook, hooks basados en prompt y en agente, y la advertencia de seguridad sobre que los hooks se ejecutan con tus permisos.