Хуки Claude Code — это определяемые пользователем команды оболочки, которые выполняются в различных точках жизненного цикла Claude Code. Хуки обеспечивают детерминированный контроль над поведением Claude Code, гарантируя, что определенные действия всегда происходят, а не полагаясь на LLM для выбора их выполнения.

Для справочной документации по хукам см. Справочник по хукам.

Примеры случаев использования хуков включают:

  • Уведомления: Настройте способ получения уведомлений, когда Claude Code ожидает ваш ввод или разрешение на выполнение чего-либо.
  • Автоматическое форматирование: Запускайте prettier для .ts файлов, gofmt для .go файлов, и т.д. после каждого редактирования файла.
  • Логирование: Отслеживайте и подсчитывайте все выполненные команды для соответствия требованиям или отладки.
  • Обратная связь: Предоставляйте автоматическую обратную связь, когда Claude Code создает код, который не соответствует соглашениям вашей кодовой базы.
  • Пользовательские разрешения: Блокируйте изменения в производственных файлах или чувствительных каталогах.

Кодируя эти правила как хуки, а не инструкции в промптах, вы превращаете предложения в код уровня приложения, который выполняется каждый раз, когда ожидается его запуск.

Вы должны учитывать последствия хуков для безопасности при их добавлении, поскольку хуки запускаются автоматически во время цикла агента с учетными данными вашей текущей среды. Например, вредоносный код хуков может похитить ваши данные. Всегда проверяйте реализацию ваших хуков перед их регистрацией.

Для полных рекомендаций по безопасности см. Соображения безопасности в справочной документации по хукам.

​
Обзор событий хуков

Claude Code предоставляет несколько событий хуков, которые запускаются в разных точках рабочего процесса:

  • PreToolUse: Запускается перед вызовами инструментов (может их блокировать)
  • PostToolUse: Запускается после завершения вызовов инструментов
  • Notification: Запускается, когда Claude Code отправляет уведомления
  • Stop: Запускается, когда Claude Code завершает ответ
  • SubagentStop: Запускается, когда завершаются задачи субагента

Каждое событие получает разные данные и может контролировать поведение Claude разными способами.

​
Быстрый старт

В этом быстром старте вы добавите хук, который логирует команды оболочки, которые выполняет Claude Code.

​
Предварительные требования

Установите jq для обработки JSON в командной строке.

​
Шаг 1: Откройте конфигурацию хуков

Выполните слэш-команду /hooks и выберите событие хука PreToolUse.

Хуки PreToolUse запускаются перед вызовами инструментов и могут их блокировать, предоставляя Claude обратную связь о том, что делать по-другому.

​
Шаг 2: Добавьте сопоставитель

Выберите + Add new matcher…, чтобы запускать ваш хук только для вызовов инструмента Bash.

Введите Bash для сопоставителя.

Используйте пустую строку "" для сопоставления всех инструментов. Символ * не является допустимым сопоставителем сам по себе.

​
Шаг 3: Добавьте хук

Выберите + Add new hook… и введите эту команду:

jq -r '"\(.tool_input.command) - \(.tool_input.description // "No description")"' >> ~/.claude/bash-command-log.txt

​
Шаг 4: Сохраните вашу конфигурацию

Для места хранения выберите User settings, поскольку вы логируете в ваш домашний каталог. Этот хук будет применяться ко всем проектам, а не только к вашему текущему проекту.

Затем нажмите Esc, пока не вернетесь в REPL. Ваш хук теперь зарегистрирован!

​
Шаг 5: Проверьте ваш хук

Выполните /hooks снова или проверьте ~/.claude/settings.json, чтобы увидеть вашу конфигурацию:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"No description\")\"' >> ~/.claude/bash-command-log.txt"
          }
        ]
      }
    ]
  }
}

​
Шаг 6: Протестируйте ваш хук

Попросите Claude выполнить простую команду, например ls, и проверьте ваш файл журнала:

cat ~/.claude/bash-command-log.txt

Вы должны увидеть записи вроде:

ls - Lists files and directories

​
Больше примеров

Для полного примера реализации см. пример валидатора команд bash в нашей публичной кодовой базе.

​
Хук форматирования кода

Автоматически форматируйте файлы TypeScript после редактирования:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if echo '$(.tool_input.file_path)' | grep -q '\\.ts$'; then npx prettier --write '$(.tool_input.file_path)'; fi"
          }
        ]
      }
    ]
  }
}

​
Хук пользовательских уведомлений

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

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

​
Хук защиты файлов

Блокируйте редактирование чувствительных файлов:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import json, sys; data=json.load(sys.stdin); path=data.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(p in path for p in ['.env', 'package-lock.json', '.git/']) else 0)\""
          }
        ]
      }
    ]
  }
}

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

  • Для справочной документации по хукам см. Справочник по хукам.
  • Для комплексных рекомендаций по безопасности и руководящих принципов безопасности см. Соображения безопасности в справочной документации по хукам.
  • Для шагов по устранению неполадок и техник отладки см. Отладка в справочной документации по хукам.