Hooks de Claude Code: acciones que se ejecutan siempre
Puedes escribir en tu CLAUDE.md «nunca toques el archivo de contraseñas», y casi siempre funcionará. Casi. Un hook es la versión que no depende de que Claude se acuerde: un comando que se ejecuta siempre en un momento fijo, antes o después de lo que haga la IA. Aquí va qué es, en qué momentos se dispara, 3 ejemplos útiles y lo que un hook no ve.
- 01Qué esPedírselo a Claude vs. que pase siempre
- 02Qué esLos momentos en que se dispara un hook
- 03Decidir3 hooks útiles para empezar
- 04Paso a pasoCómo se crea y cómo se comprueba
- 05CuidadoLo que un hook no ve
- 06PromptsUn prompt para que Claude escriba tu hook
- 07CuidadoLo honesto
Qué es un hook: pedírselo a Claude vs. que pase siempre
La documentación oficial define los hooks como comandos que tú defines y que Claude Code ejecuta en puntos concretos de su funcionamiento. Su ventaja es el control: ciertas acciones pasan siempre, en vez de depender de que el modelo decida hacerlas. (Claude Code Docs · hooks)
La diferencia con CLAUDE.md es la clave de todo:
| CLAUDE.md | Hook | |
|---|---|---|
| Qué es | Instrucciones que Claude lee | Un comando que Claude Code ejecuta |
| ¿Se cumple siempre? | Casi siempre: es contexto, no una orden | Sí: no depende de que la IA se acuerde |
| Para qué | Cómo trabajar, tono, convenciones | Lo que no puede fallar nunca |
La propia documentación de la memoria lo recomienda: si algo tiene que pasar en un momento concreto, como antes de cada commit o después de cada edición, escríbelo como hook. (Claude Code Docs · memory)
Piensa en el cinturón de seguridad que suena. Puedes pedirle a alguien que se lo ponga (CLAUDE.md). El pitido que no para hasta que se lo pone es el hook.
Los momentos en que se dispara un hook
Cada hook se engancha a un momento (la documentación los llama «eventos»). Hay más de treinta; estos son los que más se usan: (Claude Code Docs · hooks)
| Momento | Cuándo pasa | Para qué sirve |
|---|---|---|
SessionStart | Al empezar o retomar una sesión | Recordarle a Claude algo importante |
UserPromptSubmit | Cuando envías un mensaje, antes de que Claude lo lea | Añadir contexto a cada pedido |
PreToolUse | Antes de que Claude use una herramienta | Bloquear una acción antes de que pase |
PostToolUse | Después de que la herramienta funcionó | Ordenar o revisar lo que cambió |
Notification | Cuando Claude necesita tu atención | Avisarte en tu pantalla |
Stop | Cuando Claude termina de responder | Una revisión final de cada turno |
PreCompact | Antes de resumir la conversación para hacer sitio | Guardar algo antes de que se pierda |
Un hook de PreToolUse puede frenar la acción: si termina con el código de salida 2, Claude Code la bloquea y le pasa a Claude el motivo, para que busque otro camino.
3 hooks útiles para empezar
Los tres vienen de la guía oficial, que trae el código listo para copiar: (Claude Code Docs · hooks)
1 · Que te avise cuando te necesita
Momento Notification. Recibes un aviso en la pantalla cuando Claude espera tu permiso o tu respuesta, y puedes hacer otra cosa mientras trabaja. La guía trae la versión para Mac, Linux y Windows.
2 · Proteger archivos que no se tocan
Momento PreToolUse, antes de cada edición. Si el archivo es de contraseñas (.env) u otro de tu lista, el hook lo bloquea y le explica a Claude por qué.
3 · Recordar reglas después de resumir
Momento SessionStart, al retomar tras un resumen. Cuando la conversación se compacta se pierden detalles; el hook vuelve a meter lo importante, como «corre las pruebas antes de guardar».
Nuestro ejemplo real
En IActn, un hook hace una copia de cada archivo antes de que Claude lo edite. Si una edición sale mal, el original está a salvo aunque nadie se haya acordado de copiarlo.
Git tiene sus propios hooks, que son otra cosa: se disparan en momentos de git, como justo antes de un commit (pre-commit). El control que revisa que no se cuelen claves en nuestros commits es de ese tipo. (Pro Git · Puntos de enganche)
Cómo se crea un hook y cómo se comprueba
- Se escribe en un archivo de configuración. Para que valga en todos tus proyectos, en
~/.claude/settings.json; para uno solo, en.claude/settings.jsondentro de la carpeta del proyecto. La documentación dice que también puedes pedirle a Claude que lo escriba describiendo lo que quieres. - Tiene tres partes: el momento (por ejemplo
PostToolUse), un filtro opcional que dice a qué herramientas aplica (por ejemploEdit|Write, solo ediciones de archivos) y el comando que se ejecuta. - Comprueba que quedó registrado con este comando dentro de Claude Code. Lista los momentos y cuántos hooks tiene cada uno. Es solo para mirar: para cambiar algo se edita el archivo o se le pide a Claude.
/hooks - Pruébalo provocando el caso. Si es un hook que protege un archivo, pídele a Claude que lo edite y mira que lo bloquee. Un hook que nunca viste funcionar no protege nada.
Así se ve el tercer ejemplo de arriba en el archivo de configuración (adaptado de la documentación oficial; el texto del recordatorio es el suyo, en inglés):
{
"hooks": {
"SessionStart": [
{
"matcher": "compact",
"hooks": [
{ "type": "command", "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing.'" }
]
}
]
}
}Lo que un hook no ve
Un hook solo se entera de lo que pasa por el momento y el filtro que le pusiste. La documentación avisa del caso que más confunde: un hook que vigila las ediciones (Edit|Write) no ve los archivos que Claude cambia con un comando de terminal. Si tu hook tiene que ver todos los cambios, hay que vigilar también la terminal o revisar el proyecto al final de cada turno. (Claude Code Docs · hooks)
Nos pasó: nuestro hook de copias vigilaba las ediciones, y lo dimos por completo. El 16-09-2026 medimos que un cambio hecho por la terminal no dejaba copia. Ahora la regla lo dice por escrito: para esos casos, la copia se hace a mano.
Y un segundo cuidado de la misma guía: si usas un hook para aprobar permisos automáticamente, pon el filtro lo más estrecho posible. La documentación avisa que un filtro vacío aprobaría todos los permisos, también escribir archivos y ejecutar comandos.
Un prompt para que Claude escriba tu hook
Es nuestro, no de Anthropic.
Del «siempre se me olvida» al hook
Cuándo usarlo: cuando notas que le pides a Claude lo mismo en cada sesión, o que algo no puede fallar nunca.
Lo honesto
- Un hook ejecuta comandos en tu computadora. Antes de copiar el de otra persona, entiende qué hace. Si no lo entiendes, pídele a Claude que te lo explique línea por línea.
- Los ejemplos de la documentación usan herramientas de Mac y Linux. En Windows cambian los comandos; la guía oficial trae algunas versiones para Windows, no todas.
- Hay más de treinta momentos y cambian con las versiones. La tabla de arriba son los más usados según la guía al 30-09-2026; la lista completa está en la referencia oficial.
- Es de Claude Code. En el chat de claude.ai no hay hooks.
- Un hook no reemplaza a mirar. Protege de lo que previste. Lo que no se te ocurrió, no lo vigila nadie.
Lo que le pides a Claude, casi siempre lo hace; lo que pones en un hook, pasa siempre. Usa CLAUDE.md para cómo trabajar y un hook para lo que no puede fallar, y pruébalo provocando el caso antes de confiar en él. Si todavía no guardas versiones de tu proyecto, empieza por el commit.
¿Y ahora qué?
Tres formas de seguir, según lo que prefieras.
El mensaje para tu grupo
¿Le sirve a alguien de tu equipo o de tu grupo? Cópialo tal cual o ábrelo directo en WhatsApp.
Te paso esta guía: Hooks de Claude Code. Lo que no puede fallar, sin depender de que se acuerde. https://iactn.com/arsenal/hooks-de-claude-code/Fuentes, leídas el 30-09-2026
- Automate actions with hooks · Claude Code Docs. Qué es un hook, los momentos, los ejemplos (aviso, archivos protegidos, contexto tras compactar), el código de salida 2,
/hooks, lo que no ve un filtroEdit|Writey el cuidado con aprobar permisos. - How Claude remembers your project · Claude Code Docs. CLAUDE.md es contexto; lo que debe pasar en un momento fijo va en un hook.
- Personalización de Git · Puntos de enganche en Git · libro oficial Pro Git, en español. Los hooks de git, como
pre-commit.