Hook Pipeline

Бинарный файл precc-hook — это ядро PRECC. Он располагается между Claude Code и оболочкой, обрабатывая каждую bash-команду менее чем за 5 миллисекунд.

Как Claude Code вызывает hook

Claude Code поддерживает PreToolUse hook — внешние программы, которые могут проверять и модифицировать входные данные инструментов перед выполнением. Когда Claude собирается выполнить bash-команду, он отправляет JSON в precc-hook через stdin и читает ответ из stdout.

Этапы pipeline

Claude Code
    |
    v
+---------------------------+
| 1. Parse JSON stdin       |  Read the command from Claude Code
+---------------------------+
    |
    v
+---------------------------+
| 2. Skill matching         |  Query heuristics.db for matching skills (Pillar 4)
+---------------------------+
    |
    v
+---------------------------+
| 3. Directory correction   |  Resolve correct working directory (Pillar 1)
+---------------------------+
    |
    v
+---------------------------+
| 4. GDB check              |  Detect debug opportunities (Pillar 2)
+---------------------------+
    |
    v
+---------------------------+
| 5. RTK rewriting          |  Apply command rewrites for token savings
+---------------------------+
    |
    v
+---------------------------+
| 6. Emit JSON stdout       |  Return modified command to Claude Code
+---------------------------+
    |
    v
  Shell executes corrected command

Пример: JSON вход и выход

Вход (от Claude Code)

{
  "tool_input": {
    "command": "cargo build"
  }
}

PRECC обнаруживает, что в текущей директории нет Cargo.toml, но ./myapp/Cargo.toml существует.

Выход (к Claude Code)

{
  "hookSpecificOutput": {
    "updatedInput": {
      "command": "cd /home/user/projects/myapp && cargo build"
    }
  }
}

Если модификация не требуется, updatedInput.command пуст, и Claude Code использует исходную команду.

Детали этапов

Этап 1: Парсинг JSON

Считывает полный JSON-объект из stdin. Извлекает tool_input.command. При ошибке парсинга hook немедленно завершается, и Claude Code использует исходную команду (fail-open дизайн).

Этап 2: Сопоставление навыков

Запрашивает базу данных SQLite эвристик для навыков, чей паттерн-триггер совпадает с командой. Навыки проверяются в порядке приоритета. Оцениваются как встроенные TOML-навыки, так и изученные.

Этап 3: Коррекция директории

Для команд сборки (cargo, go, make, npm, python и т.д.) проверяет, существует ли ожидаемый файл проекта в текущей директории. Если нет, сканирует ближайшие директории и добавляет cd <dir> &&.

Сканирование директорий использует кэшированный индекс файловой системы с TTL 5 секунд для быстродействия.

Этап 4: Проверка GDB

Если команда может вызвать крах (например, запуск отладочного бинарника), PRECC может предложить или внедрить обёртки GDB для получения структурированного отладочного вывода вместо необработанных дампов.

Этап 5: Перезапись RTK

Применяет правила RTK (Rewrite Toolkit), которые сокращают многословные команды, подавляют шумный вывод или реструктурируют команды для эффективности токенов.

Этап 6: Вывод JSON

Сериализует модифицированную команду обратно в JSON и записывает в stdout. Если изменений не было, выход сигнализирует Claude Code использовать исходную команду.

Производительность

Весь pipeline завершается менее чем за 5 миллисекунд (p99). Ключевые оптимизации:

• SQLite в режиме WAL для параллельного чтения без блокировок
• Предварительно скомпилированные regex-паттерны для сопоставления навыков
• Кэшированное сканирование файловой системы (TTL 5 секунд)
• Никаких сетевых вызовов в критическом пути
• Fail-open: любая ошибка пропускает к исходной команде

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

Вы можете вызвать hook напрямую:

$ echo '{"tool_input":{"command":"cargo build"}}' | precc-hook
{"hookSpecificOutput":{"updatedInput":{"command":"cd /home/user/myapp && cargo build"}}}