Хуки Claude Code и Git — Документация CodeGraph

Здесь описан набор .claude/hooks из исходного checkout CodeGraph. Он добавляет CPG-контекст в сеанс Claude Code рядом с промптами, правками, командами, коммитами и итоговым ответом. Это интеграция для сопровождающих репозитория, а не переносимый клиентский плагин.

В CodeGraph также есть .codex/hooks для Codex. У каталогов разные события и контракты, поэтому они не взаимозаменяемы. Для клиентского Codex используется пакетный плагин, для OpenCode — opencode-codegraph.

Зарегистрированные хуки

Источник регистрации — .claude/settings.json:

Зарегистрированные хуки
Событие Claude	Скрипт	Назначение
`SessionStart`	`session_context.py`	Определить проект и показать scope/status CPG
`UserPromptSubmit`	`enrich_prompt.py`	Добавить найденные символы и базовые факты графа
`PreToolUse`	`pre_tool_use.py`	Предупредить перед поддерживаемыми Edit/Write
`PostToolUse` для Bash	`cli_error_monitor.py`	Объяснить известные ошибки CLI
`PostToolUse` для Bash	`commit_analysis.py`	Проверить выполненный Git-коммит и свежесть CPG
`Stop`	`post_analysis.py`	Добавить финальные предупреждения по упомянутым файлам

Хуки возвращают контекст и предупреждения. Защита Git, CI, ревью и релизные шлюзы работают отдельными уровнями. Блокировка правки подтверждается статусом соответствующего шлюза.

Граница установки

В текущем settings-файле записан абсолютный путь рабочего места сопровождающего. Не копируйте его на другую машину. Подставьте абсолютный путь локального checkout и используемый Python, например:

{
  "type": "command",
  "command": "python <absolute-repository-path>/.claude/hooks/session_context.py",
  "timeout": 10000
}

Файл .claude/settings.json должен оставаться валидным JSON. matcher — строка; у текущих PostToolUse-хуков для shell задано "Bash". После изменения регистрации запустите новый сеанс.

Поведение runtime

Хуки читают структурированный JSON из stdin и возвращают Claude-совместимый JSON в stdout. CPG запрашивается через GoCPG subprocess в .claude/hooks/_utils.py; открывать DuckDB проекта напрямую из хука нельзя. Проект определяется по checkout и кэшируется в .claude/.cache.

Метрики по возможности пишутся в data/hook_metrics.jsonl либо по пути CODEGRAPH_HOOK_METRICS_FILE. Поля, похожие на секреты, редактируются, но диагностический лог всё равно нужно защищать.

Проверка перед использованием

python -m json.tool .claude/settings.json
python -m pytest tests/unit/hooks -q
python -m src.cli review --staged --format json

Первая команда проверяет синтаксис, тесты — локальные контракты, review — актуальный CLI ревью. Загрузку настроек Claude Code подтверждают чистый сеанс, результат SessionStart и одно предупреждение перед ограниченной правкой.

Ожидания от Git и CPG

commit_analysis.py реагирует только после результата Bash, соответствующего Git-коммиту. В пределах таймаута он может обновить или проверить CPG и выдать blast radius либо замечания по качеству. Timeout, отсутствие CPG, частичный scope и advisory-вывод нужно показывать явно, а не превращать в успешное ревью.

Для решения о приёмке используйте канонический сценарий:

python -m src.cli review --base-ref origin/main --format json

Диагностика и удаление

Нет вывода: проверьте событие, абсолютный путь, Python, JSON в stdin и timeout.
Выбран не тот проект: очистите запись этого checkout в .claude/.cache и начните новый сеанс.
Граф устарел: обновите проект поддерживаемым способом до использования CPG-выводов.
Для удаления уберите только нужные регистрации из настроек Claude. Не удаляйте вместе с ними .codex/hooks или конфигурацию OpenCode.

Источник истины

Регистрация: .claude/settings.json
Реализация: .claude/hooks
Отдельная реализация Codex: .codex/hooks
Сценарий ревью: Ревью кода