Автоматизация рабочих процессов с помощью hooks

​

Настройка вашего первого hook

osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'

notify-send 'Claude Code' 'Claude Code needs your attention'

powershell.exe -Command "[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')"

​

Что вы можете автоматизировать

• Получайте уведомления, когда Claude требует ввода
• Автоматическое форматирование кода после редактирования
• Блокировка редактирования защищённых файлов
• Повторное внедрение контекста после компактирования
• Аудит изменений конфигурации

​

Получайте уведомления, когда Claude требует ввода

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

{
  "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')\""
          }
        ]
      }
    ]
  }
}

​

Автоматическое форматирование кода после редактирования

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

​

Блокировка редактирования защищённых файлов

#!/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"
          }
        ]
      }
    ]
  }
}

​

Повторное внедрение контекста после компактирования

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

​

Аудит изменений конфигурации

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

​

Как работают hooks

• "type": "http": POST данные события на URL. См. HTTP hooks.
• "type": "prompt": однооборотная оценка LLM. См. Hooks на основе подсказок.
• "type": "agent": многооборотная проверка с доступом к инструментам. См. Hooks на основе агентов.

​

Чтение ввода и возврат вывода

​

Ввод hook

{
  "session_id": "abc123",          // уникальный ID для этого сеанса
  "cwd": "/Users/sarah/myproject", // рабочий каталог при срабатывании события
  "hook_event_name": "PreToolUse", // какое событие запустило этот hook
  "tool_name": "Bash",             // инструмент, который Claude собирается использовать
  "tool_input": {                  // аргументы, которые Claude передал инструменту
    "command": "npm test"          // для Bash это команда оболочки
  }
}

​

Вывод 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 становится обратной связью Claude
  exit 2 # exit 2 = заблокировать действие
fi

exit 0  # exit 0 = позволить ему продолжиться

• Exit 0: действие продолжается. Для hooks UserPromptSubmit и SessionStart всё, что вы пишете в stdout, добавляется в контекст Claude.
• Exit 2: действие заблокировано. Напишите причину в stderr, и Claude получит её как обратную связь, чтобы он мог скорректировать.
• Любой другой код выхода: действие продолжается. Stderr регистрируется, но не показывается Claude. Переключите режим подробности с помощью Ctrl+O, чтобы увидеть эти сообщения в стенограмме.

​

Структурированный вывод JSON

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

• "allow": продолжить без отображения подсказки разрешения
• "deny": отменить вызов инструмента и отправить причину Claude
• "ask": показать подсказку разрешения пользователю как обычно

​

Фильтрация hooks с помощью 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"
          }
        ]
      }
    ]
  }
}

​

Настройка местоположения hook

​

Hooks на основе подсказок

• "ok": true: действие продолжается
• "ok": false: действие заблокировано. "reason" модели передаётся обратно Claude, чтобы он мог скорректировать.

{
  "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 на основе агентов

{
  "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"]
          }
        ]
      }
    ]
  }
}

​

Ограничения и устранение неполадок

​

Ограничения

• Hooks команд взаимодействуют только через stdout, stderr и коды выхода. Они не могут напрямую запускать команды или вызовы инструментов. HTTP hooks взаимодействуют через тело ответа вместо этого.
• Время ожидания hook по умолчанию составляет 10 минут, настраивается для каждого hook с помощью поля timeout (в секундах).
• Hooks PostToolUse не могут отменить действия, так как инструмент уже выполнен.
• Hooks PermissionRequest не срабатывают в неинтерактивном режиме (-p). Используйте hooks PreToolUse для автоматизированных решений разрешений.
• Hooks Stop срабатывают всякий раз, когда Claude завершает ответ, а не только при завершении задачи. Они не срабатывают при прерывании пользователем.

​

Hook не срабатывает

• Запустите /hooks и подтвердите, что hook появляется под правильным событием
• Проверьте, что шаблон matcher точно соответствует имени инструмента (matchers чувствительны к регистру)
• Убедитесь, что вы запускаете правильный тип события (например, PreToolUse срабатывает перед выполнением инструмента, PostToolUse срабатывает после)
• Если используете hooks PermissionRequest в неинтерактивном режиме (-p), переключитесь на PreToolUse вместо этого

​

Ошибка hook в выводе

• Ваш скрипт неожиданно вышел с ненулевым кодом. Протестируйте его вручную, передав образец JSON:
  Сообщить о неправильном коде

  Копировать

  Спросить AI

  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?  # Проверьте код выхода
  
• Если вы видите “command not found”, используйте абсолютные пути или $CLAUDE_PROJECT_DIR для ссылки на скрипты
• Если вы видите “jq: command not found”, установите jq или используйте Python/Node.js для анализа JSON
• Если скрипт вообще не запускается, сделайте его исполняемым: chmod +x ./my-hook.sh

​

/hooks показывает, что hooks не настроены

• Перезагрузите сеанс или откройте /hooks для перезагрузки. Hooks, добавленные через меню /hooks, вступают в силу немедленно, но ручные редактирования файлов требуют перезагрузки.
• Убедитесь, что ваш JSON действителен (запятые в конце и комментарии не допускаются)
• Подтвердите, что файл параметров находится в правильном месте: .claude/settings.json для hooks проекта, ~/.claude/settings.json для глобальных hooks

​

Hook Stop работает бесконечно

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Позволить Claude остановиться
fi
# ... остальная логика hook

​

Ошибка валидации JSON

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

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

​

Методы отладки

​

Узнайте больше

• Справочник Hooks: полные схемы событий, формат вывода JSON, асинхронные hooks и MCP tool hooks
• Соображения безопасности: просмотрите перед развёртыванием hooks в общих или производственных средах
• Пример валидатора команд Bash: полная эталонная реализация