Короткий огляд: Хуки Claude Code — це скрипти автоматизації, які виконуються на певних етапах життєвого циклу під час сеансів кодування зі штучним інтелектом, дозволяючи розробникам запускати власні команди, перевіряти дії, форматувати код, надсилати сповіщення та застосовувати правила проєкту. Ці хуки інтегруються з робочим процесом Claude через події, такі як SessionStart, PreToolUse та PostToolUse, підтримуючи шаблони виконання на основі команд, HTTP та підказок із конфігурованими таймаутами та поведінкою вихідного коду.
Система хуків Claude Code перетворює помічника для кодування зі штучним інтелектом з корисного інструменту на повністю автоматизоване середовище розробки. Більшість розробників не усвідомлюють ступеня контролю, доступного через хуки.
Ось у чому справа — хуки — це не лише про виконання скриптів після редагування файлів. Вони надають точки перехоплення протягом усього процесу прийняття рішень Claude. Перед виконанням команди. Після збою виклику інструменту. Коли йому потрібен дозвіл. Навіть перед обробкою підказок користувача.
Цей посібник охоплює все, що надає офіційна документація, а також практичні шаблони, які, як показують обговорення в спільноті, дійсно працюють у виробничих середовищах.
Що насправді роблять хуки Claude Code
Згідно з офіційною документацією Claude Code, хуки — це визначені користувачем команди оболонки, кінцеві точки HTTP або ін'єкції підказок, які виконуються в певні моменти життєвого циклу Claude Code. Вони отримують структурований JSON-ввід через stdin і контролюють робочий процес за допомогою вихідних кодів або HTTP-відповідей.
Автоматизація заходить глибше, ніж пропонують більшість посібників. Хуки можуть повністю блокувати виконання інструментів, вставляти додатковий контекст у міркування Claude, запускати зовнішні служби та застосовувати правила валідації, яких Claude повинен дотримуватися.
Існують три основні типи хуків:
- Хуки команд: скрипти оболонки, які взаємодіють через stdout, stderr та вихідні коди
- HTTP-хуки: віддалені кінцеві точки, які отримують POST-запити та повертають JSON-відповіді
- Хуки підказок: динамічні інструкції, що вставляються в контекст Claude під час певних подій
Кожен тип слугує різним шаблонам автоматизації. Хуки команд обробляють локальну валідацію та форматування. HTTP-хуки інтегруються із зовнішніми службами та базами даних. Хуки підказок змінюють поведінку Claude без зовнішніх процесів.
Життєвий цикл хуків та система подій
Офіційна документація визначає кілька подій хуків (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification та інші), які спрацьовують під час виконання Claude Code. Розуміння того, коли спрацьовує кожна з них, визначає, яка автоматизація стає можливою.
| Подія | Коли спрацьовує | Може блокувати |
|---|---|---|
| SessionStart | Коли сеанс починається або відновлюється | Ні |
| UserPromptSubmit | Коли ви надсилаєте підказку, перед тим, як Claude її обробить | Так |
| PreToolUse | Перед виконанням виклику інструменту | Так |
| PermissionRequest | Коли з'являється діалогове вікно дозволу | Так |
| PostToolUse | Після успішного виклику інструменту | Ні |
| PostToolUseFailure | Після збою виклику інструменту | Ні |
| Notification | Коли Claude Code надсилає сповіщення | Ні |
| SubmitMessage | Коли Claude надсилає повідомлення користувачеві | Ні |
| ContextCompaction | Коли вікно контексту наближається до межі | Ні |
Можливість блокування має найбільше значення. Хуки PreToolUse можуть запобігти небезпечним операціям перед їх виконанням. Вихідний код 1 блокує дію. Вихідний код 0 дозволяє її. Вихідний код 2 спонукає Claude переглянути.
Але зачекайте. Хуки PostToolUse не можуть скасувати дії, оскільки інструмент уже був виконаний. Це обмеження формує структуру логіки валідації. Критичні перевірки належать до PreToolUse. Очищення та форматування належать до PostToolUse.
Переглядайте переваги AI Tools під час налаштування Claude Code
Якщо ви працюєте з хуками Claude Code, ви також можете обирати інші інструменти ШІ навколо вашого робочого процесу. Get AI Perks збирає стартові кредити та знижки на програмне забезпечення для інструментів ШІ та хмарних обчислень в одному місці. Платформа містить понад 200 пропозицій із умовами отримання переваг та інструкціями для кожної з них.
Шукаєте переваги Claude чи інших AI Tools?
Перегляньте Get AI Perks, щоб:
- переглянути пропозиції Claude та інших AI Tools
- порівняти умови отримання переваг перед поданням заявки
- знайти стартові знижки на весь стек ваших інструментів
👉 Відвідайте Get AI Perks, щоб дослідити поточні переваги програмного забезпечення ШІ.
Конфігурація та структура файлів
Хуки визначаються у файлі .claude/settings.json у проєкті. Схема конфігурації підтримує глобальні хуки та специфічні для інструментів збіги, які фільтрують, коли хуки виконуються.
Базова структура командного хука:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
Змінна ${file} розширюється до фактичного шляху файлу з вводу інструменту. Згідно з офіційною документацією, хуки підтримують такі розширення змінних у полях command та args.
Ієрархія розташування хуків
Claude Code перевіряє кілька розташувань для визначень хуків з чітким порядком пріоритету:
- Рівень проєкту: .claude/settings.json у поточному робочому просторі
- Рівень користувача: ~/.claude/settings.json для всіх сеансів
- Надано плагіном: хуки, що входять до комплекту встановлених плагінів
Проєктні хуки замінюють користувацькі хуки для тієї самої події. Це дозволяє застосовувати проєктно-специфічні правила форматування, зберігаючи при цьому глобальні обробники сповіщень.
Шаблони зіставлення для вибіркового виконання
Система зіставлення фільтрує хуки для конкретних інструментів або умов. Без зіставлень хуки спрацьовують для кожного випадку їхньої події.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
Поле pathPattern приймає синтаксис glob. Поле toolName зіставляється з вбудованими інструментами Claude, такими як edit_file, execute_command, read_file та create_directory.
Обговорення в спільноті показують, що комбінації зіставлень працюють за логікою AND. Усі вказані зіставлення повинні збігатися, щоб хук виконався.
Хуки команд: Інтеграція скриптів оболонки
Хуки команд виконують команди оболонки або скрипти зі структурованим JSON-вводом. Вони є найпоширенішим типом хуків для локальної автоматизації.
Офіційна документація визначає, що хуки команд отримують JSON через stdin із такою структурою:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Скрипти розбирають цей ввід для прийняття рішень. Хук валідації Python може виглядати так:#!/usr/bin/env python3 import sys import json input_data = json.load(sys.stdin) tool_input = input_data.get(‘toolInput’, {}) file_path = tool_input.get(‘path’, ”) if file_path.startswith(‘protected/’): print(“Cannot edit protected files”, file=sys.stderr) sys.exit(1) sys.exit(0) |
Вихідний код 0 дозволяє операцію. Вихідний код 1 блокує її та показує повідомлення stderr для Claude. Вихідний код 2 викликає спеціальну поведінку залежно від події.
Поведінка вихідного коду 2
Згідно з офіційною документацією щодо довідника хуків, вихідний код 2 має специфічне для події значення (PreToolUse: блокує та спонукає до перегляду; UserPromptSubmit: надає контекст без блокування; PermissionRequest: блокує дозвіл):
- PreToolUse: блокує інструмент та спонукає Claude переглянути з повідомленням stderr як контекстом
- UserPromptSubmit: надає вивід stderr як додатковий контекст без блокування
- PermissionRequest: блокує надання дозволу
Це створює проміжний варіант між жорстким блокуванням та дозволом. Claude отримує відгук про те, чому дія може бути проблематичною, і може скоригувати свій підхід.
Асинхронні хуки команд
Прапорець async: true запускає хуки у фоновому режимі, не блокуючи робочий процес Claude. Це важливо для повільних операцій, таких як сповіщення про розгортання або збір метрик.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Коли спрацьовує асинхронний хук, Claude Code запускає процес і продовжує негайно. Поле timeout встановлює максимальний час виконання в секундах. Якщо не вказано, асинхронні хуки використовують стандартний таймаут 10 хвилин.
Якщо говорити прямо: асинхронні хуки не можуть блокувати операції, оскільки вони запускаються після того, як Claude продовжує. Вони працюють для журналювання, сповіщень та очищення — не для валідації.
HTTP-хуки: Інтеграція зовнішніх служб
HTTP-хуки надсилають JSON-корисне навантаження на віддалені кінцеві точки та розбирають відповіді для контролю прийняття рішень. Вони дозволяють інтеграцію зі службами валідації, базами даних та сторонніми інструментами.
Базова конфігурація HTTP-хука:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
Структура корисного навантаження відповідає вводу командного хука, але надходить як тіло HTTP POST. Відповідь визначає наступну дію Claude.
Обробка HTTP-відповідей
Згідно з офіційною документацією, HTTP-хуки інтерпретують відповіді на основі коду стану та вмісту тіла:
| Код стану | Ефект | Джерело повідомлення |
|---|---|---|
| 200 | Дозволити операцію | Тіло відповіді (необов'язково) |
| 400 | Блокувати операцію | Тіло відповіді, показане Claude |
| 500 | Помилка хука, дозволити операцію | Записано в журнал, але не показано Claude |
| Інший | Дозволити операцію | Збій хука не блокує робочий процес |
Тіло відповіді може містити поле повідомлення, яке Claude бачить як контекст. Це дозволяє службам валідації пояснити, чому операція була заблокована.
Інтерполяція змінних середовища
HTTP-хуки підтримують синтаксис ${VAR} у url, headers та інших полях рядків. Змінні розширюються з середовища, де працює Claude Code.
Згідно з офіційною документацією MCP, розширення змінних середовища включає синтаксис стандартного резервного значення: ${VAR:-default} розширюється до VAR, якщо встановлено, інакше використовується значення за замовчуванням.
Обмеження безпеки: згідно з проблемою GitHub #28044, HTTP-хуки можуть отримати доступ лише до змінних середовища, явно зазначених у полі конфігурації allowedEnvVars. Це запобігає випадковому розкриттю облікових даних.
Хуки підказок: Ін'єкція контексту
Хуки підказок вставляють динамічні інструкції в контекст Claude під час певних подій. Вони змінюють поведінку без зовнішніх процесів або викликів API.
| { “event”: “SessionStart”, “prompt”: “Ви працюєте над проєктом TypeScript. Завжди використовуйте суворі перевірки на null та надавайте перевагу async/await над promises.” } |
Вставлений текст стає частиною системних інструкцій Claude для цього сеансу. Хуки підказок також можуть використовувати змінні шаблону, які розширюються на основі даних події.
Динамічна генерація підказок
Згідно з офіційною документацією, хуки підказок підтримують поля команд, які генерують динамічні підказки:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
Команда отримує стандартний JSON-ввід через stdin і виводить текст підказки у stdout. Це дозволяє генерувати підказки, що залежать від контексту, на основі стану проєкту.
Хуки агентів
Хуки агентів вказують під-агента, який обробляє подію, замість прямої ін'єкції підказок. Під-агент отримує контекст про подію та може виконувати багатоетапні міркування.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “Виклик інструменту не вдався. Проаналізуйте помилку та запропонуйте виправлення.” } |
Іменований під-агент повинен бути визначений у конфігурації проєкту. Хуки агентів дозволяють складну логіку прийняття рішень, яку проста ін'єкція підказок не може забезпечити.
Практичні шаблони хуків
Обговорення в спільноті та офіційні приклади показують специфічні шаблони автоматизації, які надійно працюють у виробництві.
Автоматичне форматування коду після редагування
Найпоширеніший шаблон автоматично форматує код після того, як Claude редагує файли:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
Змінна ${toolInput.path} розширюється до шляху відредагованого файлу. PostToolUse забезпечує форматування після успішних редагувань, але не блокує робочий процес Claude.
Блокування модифікації захищених файлів
Хуки PreToolUse застосовують правила захисту файлів:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
Скрипт перевіряє цільовий шлях на відповідність захищеним шаблонам і виходить з кодом 1, щоб заблокувати заборонені редагування.
Отримуйте сповіщення, коли Claude потребує вводу
Згідно з офіційним посібником з робочого процесу, хуки Notification можуть запускати настільні сповіщення або надсилати повідомлення зовнішнім службам:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Це спрацьовує щоразу, коли Claude Code надсилає сповіщення, зокрема коли він чекає на ввід користувача або після завершення завдання.
Повторне вставлення контексту після ущільнення
Хуки ContextCompaction відновлюють важливий контекст, коли розмовне вікно заповнюється:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
Вивід команди вставляється назад у контекст Claude після того, як ущільнення видаляє старі повідомлення. Це запобігає втраті критичних проєктно-специфічних інструкцій.
Аудит змін конфігурації
Відстежуйте, коли Claude змінює конфігураційні файли:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
Асинхронне виконання запобігає блокуванню Claude під час завершення операцій git. Це створює журнал аудиту змін конфігурації без ручного етапування.
JSON-вихід та контроль рішень
Хуки команд можуть виводити структурований JSON для надання детального відгуку, що виходить за рамки простих вихідних кодів. Згідно з офіційним довідником, JSON-вихід дозволяє багатопольові відповіді, які Claude інтерпретує для прийняття рішень.
| { “allowed”: false, “message”: “Цей файл захищено політикою команди”, “suggestion”: “Створіть новий файл у src/features/ натомість” } |
Поле allowed контролює, чи відбуватиметься операція. Повідомлення відображається Claude як контекст. Поле suggestion надає альтернативні підходи.
Щоб хуки виводили JSON, вони повинні:
- Записувати дійсний JSON у stdout
- Виходити з кодом 0 (для дозволених) або 1 (для заблокованих)
- Містити щонайменше логічне поле allowed
Claude Code розбирає JSON і використовує його для покращення циклу зворотного зв'язку. Вихідні коди все ще визначають основне рішення, але JSON надає багатший контекст.
Довідник полів вводу хуків
Усі хуки отримують JSON-об'єкт через stdin із загальними полями плюс дані, специфічні для події. Розуміння повної схеми дозволяє створити більш складну логіку хуків.
Загальні поля вводу
Кожен хук отримує ці базові поля:
- event: ім'я події хука (наприклад, "PreToolUse")
- sessionId: унікальний ідентифікатор поточного сеансу Claude
- turnId: ідентифікатор поточного ходу розмови
- timestamp: позначка часу в форматі ISO 8601, коли спрацювала подія
Поля подій інструменту
Події PreToolUse, PostToolUse та PostToolUseFailure включають:
- toolName: ім'я інструменту, що викликається (edit_file, execute_command тощо)
- toolInput: об'єкт, що містить вхідні параметри інструменту
- toolResponse: дані виводу інструменту (лише PostToolUse)
- error: деталі помилки, включаючи повідомлення та код (лише PostToolUseFailure)
Структура toolInput відрізняється для різних інструментів. Для edit_file вона містить шлях і вміст. Для execute_command вона містить команду та аргументи.
Поля події дозволу
Події PermissionRequest включають:
- permissionType: тип запитуваного дозволу (file_write, command_execute тощо)
- requestedAction: конкретна дія, що вимагає дозволу
- resourcePath: шлях до файлу або ідентифікатор ресурсу, що зачіпається
Хуки інструментів MCP
Згідно з офіційною документацією щодо довідника хуків, хуки можуть зіставлятися з інструментами протоколу контексту моделі (MCP) за допомогою поля зіставлення mcpTool. Це дозволяє виконувати хуки, коли Claude використовує зовнішні інструменти, надані серверами MCP.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
Значення mcpTool зіставляється з ім'ям інструменту у форматі server-name/tool-name. Це дозволяє логіку валідації для SQL-запитів, викликів API або інших зовнішніх операцій.
Запити на нові функції на GitHub вказують на зростаючий інтерес до глибшої інтеграції MCP, включаючи хуки, які можуть переглядати сповіщення сервера MCP і реагувати на зовнішні події.
Міркування щодо безпеки
Хуки виконуються з тими самими дозволами, що й сам Claude Code. Це створює наслідки для безпеки в середовищах з багатьма користувачами та спільних конфігураціях.
Пісочниця виконання команд
Згідно з проблемою GitHub #28044, HTTP-хуки маршрутизуються через проксі-пісочницю, яка обмежує доступ до мережі та фільтрує змінні середовища. Командні хуки не мають таких обмежень — вони запускаються з повним доступом до оболонки.
Документація рекомендує такі практики:
- Ніколи не зберігайте облікові дані в командах хуків
- Використовуйте змінні середовища для конфіденційних даних
- Перевіряйте весь ввід з розширень ${…}
- Реалізуйте обмеження часу для зовнішніх служб
- Використовуйте асинхронні хуки для некритичних операцій, щоб уникнути блокування у разі збоїв
Ізоляція виконання хуків
Хуки рівня користувача в ~/.claude/settings.json застосовуються до всіх проєктів. Це створює ризики при роботі з різними рівнями довіри. Проєктні хуки замінюють користувацькі, але не можуть повністю їх вимкнути.
Меню /hooks у Claude Code показує всі активні хуки для поточного сеансу. Перегляд цього списку перед роботою над конфіденційними проєктами допомагає виявити потенційні проблеми безпеки.
Налагодження та усунення несправностей
Збої хуків не завжди чітко відображаються в розмові Claude. Офіційна документація надає кілька підходів до налагодження.
Журнали виконання хуків
Claude Code записує виконання хуків у вивід налагодження сеансу. Згідно з посібником з усунення несправностей, увімкнення налагодження виявляє:
- Які хуки збіглися для кожної події
- JSON-ввід, надісланий кожному хуку
- Вивід stdout та stderr із процесів хуків
- Вихідні коди та час виконання
- HTTP-коди стану та тіла відповідей для HTTP-хуків
Увімкніть налагодження, встановивши CLAUDE_DEBUG=1 у середовищі перед запуском Claude Code.
Тестування хуків окремо
Хуки команд можна тестувати поза Claude Code, вручну створюючи JSON-ввід:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
Це перевіряє логіку хуків, не запускаючи фактичні операції Claude. Вихідний код та вивід stdout/stderr повинні відповідати очікуваній поведінці.
Поширені збої хуків
Обговорення в спільноті виявляють такі часті проблеми:
- Помилки таймауту: стандартний 10-хвилинний таймаут занадто короткий для повільних операцій — збільште його за допомогою поля timeout
- Збої розширення шляху: змінні, такі як ${file}, не визначені для подій, які не включають контекст файлу
- Помилки дозволу: скриптам хуків не вистачає прав на виконання — запустіть chmod +x script.sh
- Помилки розбору JSON: некоректний JSON-вихід від хуків — перевірте за допомогою jq перед поверненням
- Недоступність змінних середовища: змінні не передаються до процесу хука — перевірте середовище Claude Code
Вплив хуків на продуктивність
Синхронні хуки блокують робочий процес Claude до завершення. Стандартний 10-хвилинний таймаут запобігає нескінченному зависанню, але навіть короткі затримки накопичуються під час багатьох операцій.
Практики повідомляють, що прості хуки валідації мають незначний вплив на продуктивність. Хуки форматування файлів спричиняють помітний, але прийнятний вплив на продуктивність. Виклики зовнішніх API можуть створювати тертя в робочому процесі. Важкі обчислювальні операції виграють від асинхронного виконання.
Пакетна обробка хуків
Кілька хуків можуть збігатися з тією ж подією. Згідно з довідковою документацією, хуки виконуються послідовно в порядку визначення. Якщо будь-який хук блокує операцію, наступні хуки не виконуються.
Це важливо для продуктивності. П'ять синхронних хуків по 200 мс кожен додають одну секунду на подію. Об'єднання пов'язаних перевірок в один хук зменшує накладні витрати.
Розширені шаблони
Окрім базової автоматизації, хуки дозволяють складне налаштування робочого процесу.
Станцювання ланцюгів хуків
Хуки можуть підтримувати стан між виконанням за допомогою файлів або баз даних. Хук PostToolUse може записувати успішні операції, які хук PreToolUse пізніше перевіряє:
| #!/bin/bash # Запис успішних редагувань echo “${toolInput.path}” >> .claude/edit-history.txt |
Супутній хук PreToolUse може перевіряти цю історію, щоб запобігти повторним операціям або застосувати обмеження щодо порядку.
Умовна активація хуків
Змінні середовища контролюють поведінку хуків під час виконання. Встановлення CLAUDE_SKIP_HOOKS=1 вимикає хуки для екстрених ситуацій.
Самі хуки можуть перевіряти прапорці середовища:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Застосувати сувору валідацію exit 1 fi exit 0 |
Це дозволяє поведінку в режимі розробки проти режиму виробництва без змін конфігурації.
Багатоетапна валідація
Хуки PreToolUse можуть реалізовувати багаторівневу валідацію, де вихідний код 2 дозволяє Claude продовжувати з попередженнями:
- Жорсткі збої (вихід 1): блокування небезпечних операцій
- М'які попередження (вихід 2): сповіщення Claude про необхідність перегляду
- Проходження з контекстом (вихід 0 + JSON): надання додаткової інформації
Це створює спектр валідації, більш нюансований, ніж двійковий дозвіл/відмову.
Інтеграція з CI/CD
Згідно з офіційною документацією з інтеграції платформи, Claude Code працює в середовищах CI/CD для автоматизованого огляду коду та обробки запитів. Хуки розширюють цю автоматизацію.
Робочі процеси GitHub Actions можуть визначати хуки, які застосовують групові політики під час автоматизованих сеансів:
| – name: Run Claude Code with strict hooks env: STRICT_MODE: 1 run: | claude “Review this PR and suggest improvements” |
Прапорець STRICT_MODE активує умовну логіку валідації у скриптах хуків. Це гарантує, що автоматизовані сеанси дотримуються більш жорстких правил, ніж інтерактивна розробка.
Генерація аудиту
Хуки PostToolUse в середовищах CI створюють детальні журнали аудиту всіх операцій Claude:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
Фонове журналювання не впливає на продуктивність, але надає повну історію операцій для дотримання вимог та налагодження.
Меню /hooks
Claude Code надає команду /hooks, яка відображає всі активні хуки для поточного сеансу. Згідно з офіційною документацією, це меню показує:
- Тип події хука
- Шаблони зіставлення
- Команда або кінцева точка URL
- Чи виконується хук асинхронно
- Джерело конфігурації (проєкт, користувач або плагін)
Вибір хука відображає його повну конфігурацію та дозволяє тимчасово вимкнути його для поточного сеансу.
Вимкнення або видалення хуків
Хуки можна вимкнути без видалення конфігурації, додавши "enabled": false до визначення хука. Це зберігає конфігурацію, запобігаючи виконанню.
Щоб остаточно видалити хук, видаліть його запис із відповідного файлу settings.json. Зміни набувають чинності при наступному перезапуску сеансу або при запуску /reload.
Хуки в навичках та агентах
Згідно з офіційною документацією, хуки, визначені в конфігураціях навичок або під-агентів, застосовуються лише тоді, коли виконується ця навичка або агент. Це дозволяє спеціалізовану автоматизацію для конкретних робочих процесів.
Під-агент налагодження може включати хуки, які записують усі виклики інструментів:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Ці хуки спрацьовують лише під час сеансів агента налагоджувача, а не під час звичайної роботи Claude Code.
Посилання на скрипти за шляхом
Команди хуків підтримують як відносні, так і абсолютні шляхи. Відносні шляхи вирішуються від кореня проєкту, де працює Claude Code.
Найкращі практики з обговорень спільноти:
- Зберігайте скрипти хуків у каталозі .claude/hooks/
- Використовуйте описові назви: validate-typescript.sh, а не hook1.sh
- Зробіть скрипти виконуваними: chmod +x .claude/hooks/*.sh
- Додайте рядок shebang: #!/usr/bin/env bash або #!/usr/bin/env python3
- Додайте обробку помилок за допомогою set -e у скриптах bash
Майбутні можливості хуків
Запити на нові функції на GitHub розкривають заплановані та запрошені вдосконалення хуків:
- Вбудовані скриптові хуки: визначайте логіку хуків безпосередньо в settings.json без зовнішніх файлів
- Інтеграція інструментів MCP: викликайте інструменти сервера MCP з хуків замість команд оболонки
- Співпраця між агентами: хуки, які координують роботу між екземплярами Claude на різних машинах
- Розширені типи: визначення типів TypeScript для схем вводу/виводу хуків
Згідно з проблемою GitHub #4274, запит на інтегровані типи хуків (інструмент MCP, вбудований скрипт, виклик API) спрямований на спрощення конфігурації та покращення досвіду розробника.
Часті запитання
Чи можуть хуки запобігти виконанню Claude небезпечних команд?
Так. Хуки PreToolUse можуть блокувати виконання будь-якого інструменту, виходячи з кодом 1. Це включає редагування файлів, виконання команд та виклики інструментів MCP. Хук отримує повний ввід інструменту та може перевіряти будь-які критерії перед дозволом операції.
Як налагодити хук, який не працює?
Увімкніть налагодження, встановивши CLAUDE_DEBUG=1 перед запуском Claude Code. Перевірте журнали сеансу для отримання деталей виконання хуків, включаючи, які хуки збіглися, надісланий JSON-ввід, вивід stdout/stderr та вихідні коди. Тестуйте хуки окремо, надсилаючи зразки JSON до скрипта хука.
Чи працюють хуки з усіма платформами Claude Code?
Хуки працюють у CLI, настільному додатку та розширенні VS Code. Згідно з офіційною документацією, хуки виконуються скрізь, де Claude Code працює з доступом до файлової системи. Браузерні версії Claude та мобільні додатки не підтримують хуки через обмеження пісочниці.
Чи можуть хуки змінювати відповіді або поведінку Claude?
Хуки підказок вставляють інструкції, що впливають на поведінку Claude. Хуки агентів делегують обробку подій спеціалізованим під-агентам. Однак хуки не можуть безпосередньо змінювати згенерований текст або процес міркувань Claude — вони працюють шляхом надання контексту та блокування операцій.
Яка різниця між асинхронними та синхронними хуками?
Синхронні хуки блокують робочий процес Claude до завершення або таймауту. Асинхронні хуки працюють у фоновому режимі, не блокуючи. Синхронні хуки можуть запобігти операціям через вихідні коди. Асинхронні хуки не можуть блокувати, оскільки Claude продовжує роботу до завершення хука. Використовуйте асинхронні для журналювання та сповіщень, синхронні для валідації.
Як ділитися хуками з командою?
Завантажте файл .claude/settings.json до системи контролю версій. Проєктні хуки застосовуються до всіх членів команди, які клонують репозиторій. Для загальноорганізаційних політик команди можуть підтримувати спільний файл налаштувань рівня користувача, який члени команди копіюють у ~/.claude/settings.json.
Чи можуть HTTP-хуки викликати внутрішні API за файрволами?
Так, якщо Claude Code працює в середовищі з доступом до мережі до цих API. HTTP-хуки роблять стандартні POST-запити з машини, що запускає Claude Code. Корпоративні файрволи та VPN застосовуються нормально. Проксі-пісочниця, згадана в документації, контролює розкриття змінних середовища, а не маршрутизацію мережі.
Чи збільшують хуки використання токенів Claude Code?
Хуки підказок вставляють текст у контекст Claude, що споживає токени. Хуки команд та HTTP не впливають безпосередньо на використання токенів, але їх вивід (повідомлення про помилки, пропозиції) стає частиною контексту розмови. Вихідний код 2 з пояснювальними повідомленнями додає більше контексту, ніж вихідний код 1 з простим блокуванням.
Висновок
Хуки Claude Code перетворюють ШІ-помічника з потужного інструменту на повністю автоматизовану платформу розробки. Система подій надає точки перехоплення протягом усього робочого процесу Claude — від ініціалізації сеансу до ущільнення контексту.
Хуки команд обробляють локальну валідацію та форматування. HTTP-хуки інтегрують зовнішні служби та бази даних. Хуки підказок змінюють поведінку шляхом ін'єкції контексту. Разом вони дозволяють використовувати шаблони автоматизації, які застосовують групові політики, підтримують якість коду та інтегруються з існуючою інфраструктурою розробки.
Система зіставлення фільтрує хуки для конкретних інструментів та шаблонів файлів. Вихідні коди та JSON-вихід контролюють потік рішень. Асинхронне виконання запобігає блокуванню повільних операцій. Повна схема конфігурації підтримує все: від простого автоматичного форматування до складних багатоетапних перевірок.
Почніть з базових хуків PostToolUse для форматування коду. Додайте валідацію PreToolUse, коли з'являться політики. Експериментуйте з хуками підказок для зміни поведінки. Створюйте HTTP-інтеграції для загальнокомандного застосування.
Перегляньте офіційну документацію Claude Code для повного довідника хуків та оновленої схеми конфігурації, оскільки з'являються нові можливості.
