Повний посібник із Claude Code Hooks: повний контроль над кожною дією Claude

Щоразу, коли Claude Code читає файл, пише код або виконує команду, у фоновому режимі працює система подій. Hooks — це інтерфейс для підключення до цієї системи: можна впроваджувати власну логіку будь-коли, автоматично запускати лінтери, записувати операції, блокувати небезпечні дії або запускати будь-які shell-команди.

Ця стаття повністю охоплює механізм Hooks, налаштування та практичне застосування.

Що таке Hooks

Hooks — це shell-команди, налаштовані в settings.json, які Claude Code автоматично виконує при настанні певних подій.

Найпряміша аналогія: git hooks. Git може запускати скрипти до і після операцій commit і push. Claude Code Hooks працюють точно так само — різниця в тому, що точками спрацювання є виклики інструментів ШІ.

Чому це важливо?

Що потужнішим стає Claude Code, то більше потрібен детермінований рівень контролю. Hooks забезпечують:
- Гарантії виконання, незалежні від промпту
- Журнали операцій, що перевіряються
- Автоматизовані перевірки якості

П'ять типів Hooks

Тип	Тригер	Типове використання
`PreToolUse`	До виклику інструменту	Блокування небезпечних операцій
`PostToolUse`	Після виклику інструменту	Авто-лінт, запуск тестів
`PreCompact`	До стиснення контексту	Збереження знімка стану
`Notification`	Коли Claude надсилає сповіщення	Десктопні сповіщення, Slack
`Stop`	Коли Claude завершує відповідь	Зведення логів

Формат конфігурації

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{"type": "command", "command": "npm run lint --silent"}]
      }
    ]
  }
}

Три ключові поля: matcher — regex для імен інструментів; type — лише "command"; command — будь-яка shell-команда.

Коди завершення

Код	Значення
`0`	Успіх, продовжити виконання
`2`	Блокування: скасувати виклик інструменту, передати stderr Claude
Інший ненульовий	Записати помилку, продовжити

Чотири реальні конфігурації

Автоформатування після запису файлів — PostToolUse на Write|Edit, запускає rubocop для .rb файлів.

Заборона видалення каталогів — PreToolUse на Bash, при виявленні rm .*/migrations повертає код 2.

Журнал аудиту — PostToolUse на Write|Edit|Bash, дописує в ~/.claude/audit.log.

Сповіщення після завершення — Stop hook, запускає osascript або notify-send.

Глобальний vs. рівень проєкту

Глобальний (~/.claude/settings.json): правила для всіх проєктів. Рівень проєкту (.claude/settings.json): специфічні перевірки. Обидва набори об'єднуються і виконуються разом.

Налагодження

Перевірити регістр у matcher — Write не write
Запустити команду окремо в терміналі
Перевірити stderr у виводі Claude Code
Почати з echo "triggered" >> /tmp/hook.log

Підсумок

Цінність Hooks — поєднати непередбачувану поведінку ШІ з детермінованими інженерними стандартами. Почніть з одного hook: авто-лінт після запису файлів.