Automatizar flujos de trabajo con hooks

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

Configura tu primer hook

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" }]
      }
    ]
  }
}

​

Qué puedes automatizar

• Recibe notificaciones cuando Claude necesita entrada
• Formatea automáticamente el código después de ediciones
• Bloquea ediciones a archivos protegidos
• Reinyecta contexto después de compactación
• Audita cambios de configuración
• Recarga el entorno cuando el directorio o los archivos cambian
• Aprueba automáticamente avisos de permiso específicos

​

Recibe notificaciones cuando Claude necesita entrada

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

osascript -e 'display notification "test"'

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

​

Formatea automáticamente el código después de ediciones

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

​

Bloquea ediciones a archivos protegidos

#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

chmod +x .claude/hooks/protect-files.sh

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

​

Reinyecta contexto después de compactación

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

​

Audita cambios de configuración

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

​

Recarga el entorno cuando el directorio o los archivos cambian

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ],
    "CwdChanged": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": ".envrc|.env",
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

​

Aprueba automáticamente avisos de permiso específicos

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PermissionRequest\", \"decision\": {\"behavior\": \"allow\"}}}'"
          }
        ]
      }
    ]
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedPermissions": [
        { "type": "setMode", "mode": "acceptEdits", "destination": "session" }
      ]
    }
  }
}

​

Cómo funcionan los hooks

• "type": "http": POST de datos de evento a una URL. Consulta HTTP hooks.
• "type": "mcp_tool": llamar a una herramienta en un servidor MCP ya conectado. Consulta MCP tool hooks.
• "type": "prompt": evaluación LLM de un solo turno. Consulta Prompt-based hooks.
• "type": "agent": verificación multi-turno con acceso a herramientas. Los hooks de agente son experimentales y pueden cambiar. Consulta Agent-based hooks.

​

Combina resultados de múltiples hooks

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r .tool_input.command >> ~/.claude/bash.log"
          },
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm-rf.sh"
          }
        ]
      }
    ]
  }
}

​

Lee entrada y devuelve salida

​

Entrada del hook

{
  "session_id": "abc123",          // ID único para esta sesión
  "cwd": "/Users/sarah/myproject", // directorio de trabajo cuando se activó el evento
  "hook_event_name": "PreToolUse", // qué evento activó este hook
  "tool_name": "Bash",             // la herramienta que Claude está a punto de usar
  "tool_input": {                  // los argumentos que Claude pasó a la herramienta
    "command": "npm test"          // para Bash, este es el comando de shell
  }
}

​

Salida del hook

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  # stderr se convierte en retroalimentación de Claude
  exit 2 # exit 2 = bloquea la acción
fi

exit 0  # exit 0 = permite que proceda

• Exit 0: la acción procede. Para hooks UserPromptSubmit, UserPromptExpansion, y SessionStart, cualquier cosa que escribas en stdout se añade al contexto de Claude.
• Exit 2: la acción se bloquea. Escribe una razón en stderr, y Claude la recibe como retroalimentación para que pueda ajustar. Algunos eventos no pueden ser bloqueados: para SessionStart, Setup, Notification, y otros, exit 2 muestra stderr al usuario y la ejecución continúa. Consulta comportamiento del código de salida 2 por evento para la lista completa.
• Cualquier otro código de salida: la acción procede. La transcripción muestra un aviso <hook name> hook error seguido de la primera línea de stderr; el stderr completo va al registro de depuración.

​

Salida JSON estructurada

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

• "allow": omite el aviso de permiso interactivo. Las reglas de negación y solicitud, incluyendo listas de negación gestionadas empresariales, aún se aplican
• "deny": cancela la llamada a herramienta y envía la razón a Claude
• "ask": muestra el aviso de permiso al usuario como es normal

​

Filtra hooks con matchers

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "prettier --write ..." }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "clear",
        "hooks": [
          {
            "type": "command",
            "command": "rm -f /tmp/claude-scratch-*.txt"
          }
        ]
      }
    ]
  }
}

​

Filtra por nombre de herramienta y argumentos con el campo if

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

​

Configura la ubicación del hook

​

Hooks basados en prompts

• "ok": true: la acción procede
• "ok": false: lo que sucede depende del evento:
  • Stop y SubagentStop: la reason se alimenta de vuelta a Claude para que siga trabajando
  • PreToolUse: la llamada de herramienta se deniega y la reason se devuelve a Claude como el error de la herramienta, para que pueda ajustarse y continuar
  • PostToolUse, PostToolBatch, UserPromptSubmit y UserPromptExpansion: el turno termina y la reason aparece en el chat como una línea de advertencia

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

​

Hooks basados en agentes

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

​

HTTP hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

​

Limitaciones y solución de problemas

​

Limitaciones

• Los hooks de comando se comunican solo a través de stdout, stderr y códigos de salida. No pueden activar comandos / o llamadas a herramientas. El texto devuelto a través de additionalContext se inyecta como un recordatorio del sistema que Claude lee como texto plano. Los HTTP hooks se comunican a través del cuerpo de respuesta en su lugar.
• Los tiempos de espera del hook varían según el tipo. Anule por hook con el campo timeout en segundos.
  • command, http, mcp_tool: 10 minutos. UserPromptSubmit reduce estos a 30 segundos.
  • prompt: 30 segundos.
  • agent: 60 segundos.
• Los hooks PostToolUse no pueden deshacer acciones ya que la herramienta ya se ha ejecutado.
• Los hooks PermissionRequest no se activan en modo no interactivo (-p). Usa hooks PreToolUse para decisiones de permiso automatizadas.
• Los hooks Stop se activan cada vez que Claude termina de responder, no solo en la finalización de tareas. No se activan en interrupciones del usuario. Los errores de API activan StopFailure en su lugar.
• Cuando múltiples hooks PreToolUse devuelven updatedInput para reescribir los argumentos de una herramienta, el último en terminar gana. Como los hooks se ejecutan en paralelo, el orden es no determinista. Evita tener más de un hook modificando la entrada de la misma herramienta.

​

Hooks y modos de permiso

​

Hook no se activa

• Ejecuta /hooks y confirma que el hook aparece bajo el evento correcto
• Verifica que el patrón del matcher coincida exactamente con el nombre de la herramienta (los matchers distinguen mayúsculas de minúsculas)
• Verifica que estés activando el tipo de evento correcto (por ejemplo, PreToolUse se activa antes de la ejecución de la herramienta, PostToolUse se activa después)
• Si usas hooks PermissionRequest en modo no interactivo (-p), cambia a PreToolUse en su lugar

​

Error de hook en la salida

• Tu script salió con un código no cero inesperadamente. Pruébalo manualmente canalizando JSON de muestra:
  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?  # Verifica el código de salida
  
• Si ves “command not found”, usa rutas absolutas o ${CLAUDE_PROJECT_DIR} para referenciar scripts. Para evitar entrecomillado de shell por completo, añade "args": [] para cambiar a forma exec, que genera el script directamente sin un shell
• Si ves “jq: command not found”, instala jq o usa Python/Node.js para análisis JSON
• Si el script no se ejecuta en absoluto, hazlo ejecutable: chmod +x ./my-hook.sh

​

/hooks no muestra hooks configurados

• Las ediciones de archivos normalmente se recogen automáticamente. Si no han aparecido después de unos segundos, el observador de archivos puede haber perdido el cambio: reinicia tu sesión para forzar una recarga.
• Verifica que tu JSON sea válido (las comas finales y comentarios no están permitidos)
• Confirma que el archivo de configuración está en la ubicación correcta: .claude/settings.json para hooks de proyecto, ~/.claude/settings.json para hooks globales

​

El hook Stop se ejecuta para siempre

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Permite que Claude se detenga
fi
# ... resto de tu lógica de hook

​

Falló la validación JSON

Shell ready on arm64
{"decision": "block", "reason": "Not allowed"}

# En ~/.zshrc o ~/.bashrc
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

​

Técnicas de depuración

​

Aprende más

• Referencia de Hooks: esquemas de eventos completos, formato de salida JSON, hooks asincronos y hooks de herramientas MCP
• Consideraciones de seguridad: revisa antes de desplegar hooks en entornos compartidos o de producción
• Ejemplo de validador de comandos Bash: implementación de referencia completa