Что делать, если Hooks не работают

С какой проблемой вы столкнулись

Вы настроили Hooks, но обнаружили, что они работают не так, как ожидалось? Возможно, вы столкнулись с одной из следующих ситуаций:

Dev server не блокируется при запуске вне tmux
Не видно логов SessionStart или SessionEnd
Автоматическое форматирование Prettier не срабатывает
Проверка TypeScript не запускается
Появляются странные сообщения об ошибках

Не волнуйтесь — для этих проблем обычно есть чёткие решения. В этом уроке мы систематически разберём и исправим проблемы, связанные с Hooks.

🎒 Подготовка перед началом

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

Убедитесь, что вы:

✅ Завершили установку Everything Claude Code
✅ Понимаете базовые концепции автоматизации Hooks
✅ Прочитали описание конфигурации Hooks в README проекта

Частая проблема 1: Hooks вообще не срабатывают

Симптомы

После выполнения команды не видно никакого вывода [Hook] в логах, Hooks как будто вообще не вызываются.

Возможные причины

Причина A: Неверный путь к hooks.json

Проблема: hooks.json находится не в правильном месте, Claude Code не может найти файл конфигурации.

Решение:

Проверьте, находится ли hooks.json в правильном месте:

bash

# Должен быть в одном из следующих мест:
~/.claude/hooks/hooks.json              # Конфигурация уровня пользователя (глобальная)
.claude/hooks/hooks.json                 # Конфигурация уровня проекта

Способ проверки:

bash

# Проверить конфигурацию уровня пользователя
ls -la ~/.claude/hooks/hooks.json

# Проверить конфигурацию уровня проекта
ls -la .claude/hooks/hooks.json

Если файл не существует, скопируйте его из директории плагина Everything Claude Code:

bash

# Предполагая, что плагин установлен в ~/.claude-plugins/
cp ~/.claude-plugins/everything-claude-code/hooks/hooks.json ~/.claude/hooks/

Причина B: Синтаксическая ошибка в JSON

Проблема: В hooks.json есть синтаксическая ошибка, из-за которой Claude Code не может его распарсить.

Решение:

Проверьте формат JSON:

bash

# Используйте jq или Python для проверки синтаксиса JSON
jq empty ~/.claude/hooks/hooks.json
# или
python3 -m json.tool ~/.claude/hooks/hooks.json > /dev/null

Типичные синтаксические ошибки:

Отсутствует запятая
Незакрытые кавычки
Использование одинарных кавычек (нужны двойные)
Неправильный формат комментариев (JSON не поддерживает комментарии //)

Причина C: Не установлена переменная окружения CLAUDE_PLUGIN_ROOT

Проблема: Hook-скрипты используют ${CLAUDE_PLUGIN_ROOT} для ссылки на путь, но переменная окружения не установлена.

Решение:

Проверьте правильность пути установки плагина:

bash

# Посмотреть пути установленных плагинов
ls -la ~/.claude-plugins/

Убедитесь, что плагин Everything Claude Code установлен корректно:

bash

# Должна быть примерно такая структура директорий
~/.claude-plugins/everything-claude-code/
├── scripts/
├── hooks/
├── agents/
└── ...

При установке через маркетплейс плагинов переменная окружения будет установлена автоматически после перезапуска Claude Code.

При ручной установке проверьте путь к плагину в ~/.claude/settings.json:

json

{
  "plugins": [
    {
      "name": "everything-claude-code",
      "path": "/path/to/everything-claude-code"
    }
  ]
}

Частая проблема 2: Определённый Hook не срабатывает

Симптомы

Некоторые Hooks работают (например, SessionStart), но другие не срабатывают (например, форматирование в PreToolUse).

Возможные причины

Причина A: Ошибка в выражении Matcher

Проблема: Выражение matcher в Hook содержит ошибку, из-за чего условие сопоставления не выполняется.

Решение:

Проверьте синтаксис matcher в hooks.json:

json

{
  "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.(ts|tsx)$\""
}

Важные замечания:

Имя инструмента должно быть в двойных кавычках: "Edit", "Bash"
Обратные слеши в регулярных выражениях требуют двойного экранирования: \\\\. вместо \\.
Для сопоставления путей файлов используется ключевое слово matches

Тестирование Matcher:

Вы можете вручную протестировать логику сопоставления:

bash

# Тест сопоставления пути файла
node -e "console.log(/\\\\.(ts|tsx)$/.test('src/index.ts'))"
# Должно вывести: true

Причина B: Ошибка выполнения команды

Проблема: Сама команда Hook завершается с ошибкой, но сообщение об ошибке не отображается.

Решение:

Запустите команду Hook вручную для тестирования:

bash

# Перейдите в директорию плагина
cd ~/.claude-plugins/everything-claude-code

# Вручную запустите какой-либо Hook-скрипт
node scripts/hooks/session-start.js

# Проверьте, есть ли вывод ошибок

Типичные причины сбоев:

Несовместимая версия Node.js (требуется Node.js 14+)
Отсутствуют зависимости (например, не установлены prettier, typescript)
Проблемы с правами доступа к скрипту (см. ниже)

Частая проблема 3: Проблемы с правами доступа (Linux/macOS)

Симптомы

Появляется ошибка вида:

Permission denied: node scripts/hooks/session-start.js

Решение

Добавьте права на выполнение для Hook-скриптов:

bash

# Перейдите в директорию плагина
cd ~/.claude-plugins/everything-claude-code

# Добавьте права на выполнение для всех hooks-скриптов
chmod +x scripts/hooks/*.js

# Проверьте права
ls -la scripts/hooks/
# Должно быть примерно так: -rwxr-xr-x  session-start.js

Массовое исправление всех скриптов:

bash

# Исправить все .js файлы в директории scripts
find ~/.claude-plugins/everything-claude-code/scripts -name "*.js" -exec chmod +x {} \;

Частая проблема 4: Проблемы кроссплатформенной совместимости

Симптомы

Работает нормально на Windows, но не работает на macOS/Linux; или наоборот.

Возможные причины

Причина A: Разделители путей

Проблема: Windows использует обратный слеш \, Unix использует прямой слеш /.

Решение:

Скрипты Everything Claude Code уже обрабатывают кроссплатформенность (используя модуль Node.js path), но если вы создаёте собственный Hook, обратите внимание:

Неправильно:

json

{
  "command": "node scripts/hooks\\session-start.js"  // Стиль Windows
}

Правильно:

json

{
  "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/session-start.js\"  // Используйте переменную окружения и прямые слеши
}

Причина B: Различия в командах оболочки

Проблема: Синтаксис команд различается на разных платформах (например, which vs where).

Решение:

В scripts/lib/utils.js Everything Claude Code эти различия уже обработаны. При создании собственного Hook используйте кроссплатформенные функции из этого файла:

javascript

// Кроссплатформенное определение команды в utils.js
function commandExists(cmd) {
  if (isWindows) {
    spawnSync('where', [cmd], { stdio: 'pipe' });
  } else {
    spawnSync('which', [cmd], { stdio: 'pipe' });
  }
}

Частая проблема 5: Автоформатирование не работает

Симптомы

После редактирования TypeScript-файла Prettier не форматирует код автоматически.

Возможные причины

Причина A: Prettier не установлен

Проблема: PostToolUse Hook вызывает npx prettier, но он не установлен в проекте.

Решение:

bash

# Установить Prettier (на уровне проекта)
npm install --save-dev prettier
# или
pnpm add -D prettier

# Или установить глобально
npm install -g prettier

Причина B: Отсутствует конфигурация Prettier

Проблема: Prettier не находит файл конфигурации и использует правила форматирования по умолчанию.

Решение:

Создайте файл конфигурации Prettier:

bash

# Создайте .prettierrc в корне проекта
cat > .prettierrc << 'EOF'
{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5"
}
EOF

Причина C: Тип файла не соответствует

Проблема: Расширение редактируемого файла не входит в правила сопоставления Hook.

Текущее правило сопоставления (hooks.json L92-97):

json

{
  "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.(ts|tsx|js|jsx)$\"",
  "description": "Auto-format JS/TS files with Prettier after edits"
}

Если нужна поддержка других типов файлов (например, .vue), измените конфигурацию:

json

{
  "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.(ts|tsx|js|jsx|vue)$\""
}

Частая проблема 6: Проверка TypeScript не работает

Симптомы

После редактирования .ts файла не видно вывода ошибок проверки типов.

Возможные причины

Причина A: Отсутствует tsconfig.json

Проблема: Hook-скрипт ищет файл tsconfig.json вверх по дереву директорий, но не находит его.

Решение:

Убедитесь, что в корне проекта или родительской директории есть tsconfig.json:

bash

# Поиск tsconfig.json
find . -name "tsconfig.json" -type f

# Если не существует, создайте базовую конфигурацию
cat > tsconfig.json << 'EOF'
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}
EOF

Причина B: TypeScript не установлен

Проблема: Hook вызывает npx tsc, но TypeScript не установлен.

Решение:

bash

npm install --save-dev typescript
# или
pnpm add -D typescript

Частая проблема 7: SessionStart/SessionEnd не срабатывают

Симптомы

При запуске или завершении сессии не видно логов [SessionStart] или [SessionEnd].

Возможные причины

Причина A: Директория для файлов сессий не существует

Проблема: Директория ~/.claude/sessions/ не существует, Hook-скрипт не может создать файл сессии.

Решение:

Создайте директорию вручную:

bash

# macOS/Linux
mkdir -p ~/.claude/sessions

# Windows PowerShell
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\sessions"

Причина B: Неверный путь к скрипту

Проблема: Путь к скрипту, указанный в hooks.json, некорректен.

Способ проверки:

bash

# Проверьте, существуют ли скрипты
ls -la ~/.claude-plugins/everything-claude-code/scripts/hooks/session-start.js
ls -la ~/.claude-plugins/everything-claude-code/scripts/hooks/session-end.js

Если не существуют, проверьте, полностью ли установлен плагин:

bash

# Посмотреть структуру директории плагина
ls -la ~/.claude-plugins/everything-claude-code/

Частая проблема 8: Блокировка Dev Server не работает

Симптомы

Прямой запуск npm run dev не блокируется, dev server запускается.

Возможные причины

Причина A: Регулярное выражение не совпадает

Проблема: Ваша команда dev server не входит в правила сопоставления Hook.

Текущее правило сопоставления (hooks.json L6):

json

{
  "matcher": "tool == \"Bash\" && tool_input.command matches \"(npm run dev|pnpm( run)? dev|yarn dev|bun run dev)\""
}

Тестирование сопоставления:

bash

# Проверьте, совпадает ли ваша команда
node -e "console.log(/(npm run dev|pnpm( run)? dev|yarn dev|bun run dev)/.test('npm run dev'))"

Если нужна поддержка других команд (например, npm start), измените hooks.json:

json

{
  "matcher": "tool == \"Bash\" && tool_input.command matches \"(npm (run dev|start)|pnpm( run)? (dev|start)|yarn (dev|start)|bun run (dev|start))\""
}

Причина B: Не блокируется при запуске вне tmux

Проблема: Hook должен блокировать запуск dev server вне tmux, но это не работает.

Контрольные точки:

Убедитесь, что команда Hook выполняется успешно:

bash

# Имитация команды Hook
node -e "console.error('[Hook] BLOCKED: Dev server must run in tmux');process.exit(1)"
# Должен появиться вывод ошибки и код выхода 1

Проверьте, правильно ли process.exit(1) блокирует команду:

process.exit(1) в команде Hook должен предотвращать выполнение последующих команд

Если всё ещё не работает, возможно, нужно обновить версию Claude Code (поддержка Hooks может требовать последнюю версию)

Инструменты и приёмы диагностики

Включение подробных логов

Просмотрите подробные логи Claude Code, чтобы понять выполнение Hook:

bash

# macOS/Linux
tail -f ~/Library/Logs/claude-code/claude-code.log

# Windows
Get-Content "$env:APPDATA\claude-code\logs\claude-code.log" -Wait -Tail 50

Ручное тестирование Hook

Запустите Hook-скрипт вручную в терминале для проверки его работы:

bash

# Тест SessionStart
cd ~/.claude-plugins/everything-claude-code
node scripts/hooks/session-start.js

# Тест Suggest Compact
node scripts/hooks/suggest-compact.js

# Тест PreCompact
node scripts/hooks/pre-compact.js

Проверка переменных окружения

Просмотрите переменные окружения Claude Code:

bash

# Добавьте отладочный вывод в Hook-скрипт
node -e "console.log('CLAUDE_PLUGIN_ROOT:', process.env.CLAUDE_PLUGIN_ROOT); console.log('COMPACT_THRESHOLD:', process.env.COMPACT_THRESHOLD)"

Контрольный список ✅

Проверьте по следующему списку:

[ ] hooks.json находится в правильном месте (~/.claude/hooks/ или .claude/hooks/)
[ ] Формат JSON в hooks.json корректен (проверено через jq)
[ ] Путь к плагину корректен (${CLAUDE_PLUGIN_ROOT} установлен)
[ ] Все скрипты имеют права на выполнение (Linux/macOS)
[ ] Зависимые инструменты установлены (Node.js, Prettier, TypeScript)
[ ] Директория сессий существует (~/.claude/sessions/)
[ ] Выражения Matcher корректны (экранирование регулярных выражений, кавычки)
[ ] Кроссплатформенная совместимость (использование модуля path, переменных окружения)

Когда нужна помощь

Если вышеуказанные методы не решили проблему:

Соберите диагностическую информацию:

bash

# Выведите следующую информацию
echo "Node version: $(node -v)"
echo "Claude Code version: $(claude-code --version)"
echo "Plugin path: $(ls -la ~/.claude-plugins/everything-claude-code)"
echo "Hooks config: $(cat ~/.claude/hooks/hooks.json | jq -c .)"

Посмотрите GitHub Issues:
- Перейдите на Everything Claude Code Issues
- Поищите похожие проблемы
Создайте Issue:
- Включите полный лог ошибок
- Укажите информацию об операционной системе и версии
- Приложите содержимое hooks.json (скрыв конфиденциальную информацию)

Итоги урока

Проблемы с Hooks обычно относятся к следующим категориям:

Тип проблемы	Типичные причины	Быстрая диагностика
Вообще не срабатывает	Неверный путь hooks.json, синтаксическая ошибка JSON	Проверить расположение файла, валидировать формат JSON
Определённый Hook не срабатывает	Ошибка в выражении Matcher, сбой выполнения команды	Проверить синтаксис регулярного выражения, запустить скрипт вручную
Проблемы с правами	Скрипт не имеет прав на выполнение (Linux/macOS)	`chmod +x scripts/hooks/*.js`
Кроссплатформенная совместимость	Разделители путей, различия команд оболочки	Использовать модуль `path`, см. utils.js
Функция не работает	Не установлены зависимые инструменты (Prettier, TypeScript)	Установить соответствующие инструменты, проверить файлы конфигурации

Помните: большинство проблем можно решить проверкой путей к файлам, валидацией формата JSON и подтверждением установки зависимостей.

Анонс следующего урока

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

Приложение: Справочник по исходному коду

Нажмите, чтобы развернуть расположение исходного кода

Дата обновления: 2026-01-25

Функция	Путь к файлу	Строки
Основная конфигурация Hooks	`hooks/hooks.json`	1-158
SessionStart Hook	`scripts/hooks/session-start.js`	1-62
SessionEnd Hook	`scripts/hooks/session-end.js`	1-83
PreCompact Hook	`scripts/hooks/pre-compact.js`	1-49
Suggest Compact Hook	`scripts/hooks/suggest-compact.js`	1-61
Кроссплатформенные утилиты	`scripts/lib/utils.js`	1-384

Ключевые функции:

getHomeDir() / getClaudeDir() / getSessionsDir(): Получение путей к директориям конфигурации (utils.js 19-34)
ensureDir(dirPath): Проверка существования директории, создание при отсутствии (utils.js 54-59)
log(message): Вывод лога в stderr (виден в Claude Code) (utils.js 182-184)
findFiles(dir, pattern, options): Кроссплатформенный поиск файлов (utils.js 102-149)
commandExists(cmd): Проверка существования команды (кроссплатформенная совместимость) (utils.js 228-246)

Ключевые регулярные выражения:

Блокировка Dev server: npm run dev|pnpm( run)? dev|yarn dev|bun run dev (hooks.json 6)
Сопоставление редактирования файлов: \\.(ts|tsx|js|jsx)$ (hooks.json 92)
TypeScript файлы: \\.(ts|tsx)$ (hooks.json 102)

Переменные окружения:

${CLAUDE_PLUGIN_ROOT}: Путь к корневой директории плагина
CLAUD_SESSION_ID: Идентификатор сессии
COMPACT_THRESHOLD: Порог предложения сжатия (по умолчанию 50)

Что делать, если Hooks не работают ​

С какой проблемой вы столкнулись ​

🎒 Подготовка перед началом ​

Частая проблема 1: Hooks вообще не срабатывают ​

Симптомы ​

Возможные причины ​

Причина A: Неверный путь к hooks.json ​

Причина B: Синтаксическая ошибка в JSON ​

Причина C: Не установлена переменная окружения CLAUDE_PLUGIN_ROOT ​

Частая проблема 2: Определённый Hook не срабатывает ​

Симптомы ​

Возможные причины ​

Причина A: Ошибка в выражении Matcher ​

Причина B: Ошибка выполнения команды ​

Частая проблема 3: Проблемы с правами доступа (Linux/macOS) ​

Симптомы ​

Решение ​

Частая проблема 4: Проблемы кроссплатформенной совместимости ​

Симптомы ​

Возможные причины ​

Причина A: Разделители путей ​

Причина B: Различия в командах оболочки ​

Частая проблема 5: Автоформатирование не работает ​

Симптомы ​

Возможные причины ​

Причина A: Prettier не установлен ​

Причина B: Отсутствует конфигурация Prettier ​

Причина C: Тип файла не соответствует ​

Частая проблема 6: Проверка TypeScript не работает ​

Симптомы ​

Возможные причины ​

Причина A: Отсутствует tsconfig.json ​

Причина B: TypeScript не установлен ​

Частая проблема 7: SessionStart/SessionEnd не срабатывают ​

Симптомы ​

Возможные причины ​

Причина A: Директория для файлов сессий не существует ​

Причина B: Неверный путь к скрипту ​

Частая проблема 8: Блокировка Dev Server не работает ​

Симптомы ​

Возможные причины ​

Причина A: Регулярное выражение не совпадает ​

Причина B: Не блокируется при запуске вне tmux ​

Инструменты и приёмы диагностики ​

Включение подробных логов ​

Ручное тестирование Hook ​

Проверка переменных окружения ​

Контрольный список ✅ ​

Когда нужна помощь ​

Итоги урока ​

Анонс следующего урока ​

Приложение: Справочник по исходному коду ​

Что делать, если Hooks не работают

С какой проблемой вы столкнулись

🎒 Подготовка перед началом

Частая проблема 1: Hooks вообще не срабатывают

Симптомы

Возможные причины

Причина A: Неверный путь к hooks.json

Причина B: Синтаксическая ошибка в JSON

Причина C: Не установлена переменная окружения CLAUDE_PLUGIN_ROOT

Частая проблема 2: Определённый Hook не срабатывает

Симптомы

Возможные причины

Причина A: Ошибка в выражении Matcher

Причина B: Ошибка выполнения команды

Частая проблема 3: Проблемы с правами доступа (Linux/macOS)

Симптомы

Решение

Частая проблема 4: Проблемы кроссплатформенной совместимости

Симптомы

Возможные причины

Причина A: Разделители путей

Причина B: Различия в командах оболочки

Частая проблема 5: Автоформатирование не работает

Симптомы

Возможные причины

Причина A: Prettier не установлен

Причина B: Отсутствует конфигурация Prettier

Причина C: Тип файла не соответствует

Частая проблема 6: Проверка TypeScript не работает

Симптомы

Возможные причины

Причина A: Отсутствует tsconfig.json

Причина B: TypeScript не установлен

Частая проблема 7: SessionStart/SessionEnd не срабатывают

Симптомы

Возможные причины

Причина A: Директория для файлов сессий не существует

Причина B: Неверный путь к скрипту

Частая проблема 8: Блокировка Dev Server не работает

Симптомы

Возможные причины

Причина A: Регулярное выражение не совпадает

Причина B: Не блокируется при запуске вне tmux

Инструменты и приёмы диагностики

Включение подробных логов

Ручное тестирование Hook

Проверка переменных окружения

Контрольный список ✅

Когда нужна помощь

Итоги урока

Анонс следующего урока

Приложение: Справочник по исходному коду