Guía

Cómo usar hooks en Claude Code

Quieres que algo pase siempre, como formatear un archivo después de que Claude lo edite o recibir un aviso cuando Claude te está esperando, sin confiar en que Claude se acuerde. Los hooks hacen justo eso. Esta guía explica qué son, te acompaña en un primer hook y muestra dónde ponerlos.

Actualizado 30 de octubre de 2026

Respuesta rápida: un hook es un comando de shell que Claude Code ejecuta automáticamente en un momento concreto, por ejemplo antes de que se ejecute una herramienta, después de editar un archivo o cuando Claude necesita que intervengas. Los hooks se añaden bajo una clave hooks en un archivo de configuración como ~/.claude/settings.json (todos los proyectos) o .claude/settings.json (un proyecto); después escribe /hooks para confirmar que Claude Code los ve.

Los nombres de eventos, las ubicaciones de archivos y el comportamiento de abajo proceden de la documentación de Claude Code de Anthropic en octubre de 2026. Claude Code se actualiza a menudo, así que ejecuta claude update si falta algo.

Qué son los hooks y por qué ayudan

Las instrucciones de un prompt o de un archivo CLAUDE.md son sugerencias: Claude suele seguirlas, pero decide él. Un hook es distinto. El propio Claude Code ejecuta tu comando cada vez que se produce el evento, así que la acción es determinista. Usos típicos según la guía de Anthropic:

Notificaciones cuando Claude espera un permiso o tu respuesta.
Formateo automático de cada archivo después de que Claude lo edite o lo escriba.
Bloquear ediciones de archivos sensibles como .env o cualquier cosa dentro de .git/.
Añadir contexto, por ejemplo recordarle a Claude las convenciones del proyecto después de compactar la conversación.

Algunos de los eventos más usados son SessionStart (empieza o se reanuda una sesión), UserPromptSubmit (envías un prompt), PreToolUse (antes de una llamada a una herramienta, y puede bloquearla), PostToolUse (después de que una llamada a una herramienta tenga éxito), Notification, Stop (Claude termina de responder), PreCompact y SessionEnd. La lista completa de la referencia de hooks es mucho más larga.

Configura tu primer hook: una notificación de escritorio

Este ejemplo, adaptado del tutorial de Anthropic, te avisa en macOS cada vez que Claude Code necesita tu atención.

Abre ~/.claude/settings.json en un editor de texto. Crea el archivo si no existe.
Añade un objeto hooks con una entrada Notification. Dentro va una lista de grupos de matcher; cada uno tiene un matcher (déjalo como cadena vacía para que se active con todas las notificaciones) y una lista hooks con un elemento de "type": "command".
Define el comando como osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'. En Linux, el ejemplo de Anthropic usa notify-send en su lugar. Recuerda escapar las comillas dobles interiores en el JSON.
Si el archivo ya tiene una clave hooks, añade Notification junto a los eventos existentes en lugar de sustituir el objeto entero.
En Claude Code, escribe /hooks. El explorador de hooks debería mostrar tu nuevo hook bajo Notification. Pulsa Esc para volver.
Pídele a Claude algo que necesite permiso y cambia a otra ventana. Debería aparecer una notificación.

Para que solo se active con algunas notificaciones, define el matcher como un tipo, por ejemplo permission_prompt (una solicitud de permiso lleva unos seis segundos esperando) o idle_prompt (Claude terminó y no has escrito nada durante un minuto aproximadamente).

Un segundo ejemplo: formatear archivos después de editarlos

Para un hook de proyecto, pon la configuración en .claude/settings.json, en la raíz del proyecto. Usa el evento PostToolUse con el matcher Edit|Write, para que solo se ejecute después de las herramientas que editan archivos. El comando de ejemplo de Anthropic lee la ruta editada del JSON que Claude Code pasa por la entrada estándar y se la entrega a Prettier: jq -r '.tool_input.file_path' | xargs npx prettier --write. Necesita tener jq instalado. Un hook que funciona no muestra nada en la conversación; simplemente verás el archivo reformateado.

Dónde se configuran los hooks

Ubicación	Se aplica a	¿Compartido?
`~/.claude/settings.json`	Todos tus proyectos	No, solo tu equipo
`.claude/settings.json`	Un proyecto	Sí, se puede hacer commit
`.claude/settings.local.json`	Un proyecto	No, queda fuera de git
Configuración de política gestionada	Toda la organización	La definen los administradores
El `hooks/hooks.json` de un plugin	Mientras el plugin está activado	Incluido en el plugin
Frontmatter de un skill	El resto de la sesión después de invocar el skill	En el archivo del skill
Frontmatter de un subagente	Mientras ese subagente se ejecuta	En el archivo del subagente

Para desactivar los hooks, define "disableAllHooks": true en un archivo de configuración. Los hooks de la configuración gestionada siguen ejecutándose salvo que también se defina allí.

Cómo responde un hook

Cuando se produce un evento, Claude Code envía los detalles del evento en JSON a la entrada estándar de tu comando. Tu comando responde con su código de salida:

Salida 0: continuar. En algunos eventos, como SessionStart, el texto normal que se imprime en la salida estándar se añade al contexto de Claude.
Salida 2: bloquear la acción cuando el evento lo permite. Escribe el motivo en la salida de error estándar; en PreToolUse, Claude lo recibe y puede cambiar de rumbo.
Otros códigos: normalmente se tratan como un error que no bloquea; la acción continúa y la transcripción muestra un error del hook.

Para un control más fino, sal con 0 e imprime en su lugar un objeto JSON. Elige un solo enfoque por hook.

Conviene saber

Los hooks de comando no pueden ejecutar comandos slash ni llamar ellos mismos a herramientas.
El tiempo de espera por defecto de los hooks de comando es de 10 minutos, menos en unos pocos eventos; define timeout (en segundos) en cada hook para cambiarlo.
PostToolUse no puede deshacer nada, porque la herramienta ya se ha ejecutado. Usa PreToolUse para impedir una acción.
Stop se activa cada vez que Claude termina una respuesta, no solo cuando acaba una tarea.

Si no funciona

El hook no se activa nunca: ejecuta /hooks y comprueba que aparece bajo el evento correcto. Los matchers distinguen mayúsculas y minúsculas y deben coincidir exactamente con el nombre de la herramienta, por ejemplo Edit, no edit.
«/hooks» no muestra nada: comprueba que el JSON es válido (sin comas finales ni comentarios) y que está en el archivo correcto. Los cambios normalmente se detectan solos; si no, reinicia la sesión.
«hook error» en la transcripción: prueba el script pasándole un JSON de ejemplo por tubería y comprobando echo $?. Usa rutas absolutas o $CLAUDE_PROJECT_DIR para los scripts, instala jq si falta y haz los scripts ejecutables con chmod +x.
No aparece la notificación en macOS: ejecuta una vez el comando osascript en Terminal y después activa Allow Notifications (Permitir notificaciones) para Script Editor (Editor de Scripts) en System Settings > Notifications (Ajustes del Sistema > Notificaciones).

Lleva la cuenta de lo que deja pendiente cada sesión

El plugin de Workbranch para Claude Code usa un resumen al iniciar la sesión: en una carpeta vinculada a un proyecto de Workbranch, muestra lo que sigue pendiente cuando empieza una sesión, y decir «guarda esto en Workbranch» archiva las tareas, decisiones y preguntas abiertas de la sesión en ese proyecto. Consulta Workbranch para Claude. ¿Eres nuevo en Claude Code? Empieza por cómo empezar con Claude Code.

Fuentes

Use Claude Code with your Pro or Max plan (Centro de ayuda de Claude, consultado el 30 de octubre de 2026)
Automate actions with hooks (Claude Code Docs, consultado el 30 de octubre de 2026)

Preguntas frecuentes

¿Claude puede escribirme un hook?

Sí. La guía de Anthropic dice que puedes describir el hook que quieres en el prompt de Claude Code y pedirle a Claude que lo añada a tu configuración. Comprueba el resultado después con /hooks.

¿Un hook puede detener a Claude incluso en modo bypass?

Un hook PreToolUse que devuelve una decisión deny bloquea la herramienta en todos los modos de permisos, incluido bypassPermissions. Eso es lo que hace útiles los hooks para reglas que nadie puede saltarse cambiando de modo.

¿Hay hooks que usan un modelo en lugar de un script?

Sí. Además de comandos de shell, un hook puede ser una petición HTTP, una llamada a una herramienta MCP, un único prompt evaluado por un modelo de Claude o un hook de agente experimental con acceso a herramientas.