Hooks son comandos que se ejecutan automáticamente en puntos concretos del ciclo de vida de Claude Code. A diferencia de las instrucciones en CLAUDE.md, los hooks son deterministas: si se cumple la condición, se ejecutan siempre.

Quick Tip: Hooks en Claude Code — Automatiza Tu Flujo de Trabajo

Hooks son comandos que se ejecutan automáticamente en puntos concretos del ciclo de vida de Claude Code. A diferencia de las instrucciones en CLAUDE.md (que Claude puede ignorar), los hooks son deterministas: si se cumple la condición, se ejecutan siempre. Tres tipos cubren desde validaciones simples hasta verificaciones con IA.

Para una guía completa con 5 hooks esenciales y patrones avanzados, consulta el artículo completo sobre hooks.

Resultado:

// ~/.claude/settings.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
      }]
    }]
  }
}

Los 3 tipos de hook

1. Command — Ejecuta un script

El más común. Recibe contexto vía stdin como JSON, y el exit code decide el resultado: 0 pasa, 2 bloquea.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "echo $CLAUDE_TOOL_INPUT | jq -e '.command | test(\"rm -rf|--force|DROP TABLE\") | not'"
      }]
    }]
  }
}

Este hook bloquea comandos destructivos como rm -rf, --force o DROP TABLE antes de que se ejecuten.

2. Prompt — El LLM evalúa

Para decisiones subjetivas que un script no puede resolver. Claude evalúa el contexto con un prompt en una sola pasada.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "prompt",
        "prompt": "Check that the code follows the project style guide. Block if it introduces console.log statements in production code. $ARGUMENTS"
      }]
    }]
  }
}

3. Agent — Subagente con herramientas

Para verificaciones complejas. Lanza un subagente con acceso a Read, Grep y Glob que puede inspeccionar archivos antes de decidir.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "agent",
        "prompt": "Verify that every new function has a corresponding test file. Check the test directory for matching test files. Block if tests are missing. $ARGUMENTS"
      }]
    }]
  }
}

Referencia rápida

Evento	Cuándo se dispara	Uso típico
`PreToolUse`	Antes de ejecutar una herramienta	Bloquear acciones peligrosas
`PostToolUse`	Después de una herramienta exitosa	Formatear, lint, type-check
`Notification`	Cuando Claude envía una notificación	Alertas de escritorio personalizadas
`Stop`	Cuando Claude termina su respuesta	Validación final, auto-commit
`PreCompact`	Antes de comprimir contexto	Re-inyectar instrucciones críticas
`SessionStart`	Al iniciar una sesión	Configurar entorno

Tipo	IA involucrada	Mejor para
`command`	No	Validaciones binarias (pasa/falla)
`prompt`	Sí (1 pasada)	Decisiones subjetivas
`agent`	Sí (multi-turn)	Verificaciones complejas con herramientas

Configuración

Los hooks se definen en settings.json. Tres niveles de alcance:

~/.claude/settings.json — Todos los proyectos
.claude/settings.json — Proyecto (compartible con el equipo)
.claude/settings.local.json — Proyecto (privado)

La forma más rápida de crear uno: escribe /hooks en Claude Code.

El matcher solo sabe filtrar por nombre de herramienta, así que un hook sobre Bash se lanza con cada comando. Para que solo se lance con las llamadas que te importan (git commit, archivos de src/), la entrada admite un campo if: hooks condicionales.

Relacionado: Los 6 mecanismos de extensión · Skills: comandos personalizados · Sistema de permisos

Documentación oficial: Hooks · Hooks Guide

Forma parte de los 10 hábitos para ahorrar tokens en Claude Code.

Hooks en Claude Code — Automatiza Tu Flujo de Trabajo