훅 파이프라인

precc-hook 바이너리는 PRECC의 핵심입니다. Claude Code와 셸 사이에 위치하여 모든 bash 명령을 5밀리초 이내에 처리합니다.

Claude Code가 훅을 호출하는 방법

Claude Code는 PreToolUse 훅을 지원합니다 – 실행 전에 도구 입력을 검사하고 수정할 수 있는 외부 프로그램입니다. Claude가 bash 명령을 실행하려 할 때, stdin으로 precc-hook에 JSON을 보내고 stdout에서 응답을 읽습니다.

파이프라인 단계

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 파싱

stdin에서 전체 JSON 객체를 읽습니다. tool_input.command를 추출합니다. 파싱에 실패하면 훅이 즉시 종료되고 Claude Code는 원래 명령을 사용합니다(fail-open 설계).

단계 2: 스킬 매칭

SQLite 휴리스틱 데이터베이스에서 트리거 패턴이 명령과 일치하는 스킬을 쿼리합니다. 스킬은 우선순위 순서로 확인됩니다. 내장 TOML 스킬과 마이닝된 스킬 모두 평가됩니다.

단계 3: 디렉토리 수정

빌드 명령(cargo, go, make, npm, python 등)에 대해 예상 프로젝트 파일이 현재 디렉토리에 있는지 확인합니다. 없으면 인근 디렉토리를 스캔하여 가장 가까운 일치를 찾고 cd <dir> &&를 앞에 추가합니다.

디렉토리 스캔은 5초 TTL을 가진 캐시된 파일 시스템 인덱스를 사용하여 빠른 속도를 유지합니다.

단계 4: GDB 확인

명령이 크래시를 일으킬 가능성이 있는 경우(예: 디버그 바이너리 실행), PRECC는 원시 크래시 로그 대신 구조화된 디버그 출력을 캡처하기 위해 GDB 래퍼를 제안하거나 주입할 수 있습니다.

단계 5: RTK 재작성

장황한 명령을 단축하고, 노이즈가 많은 출력을 억제하거나, 토큰 효율성을 위해 명령을 재구성하는 RTK(Rewrite Toolkit) 규칙을 적용합니다.

출력 압축은 플러그인 방식입니다. 기본적으로 PRECC는 RTK를 사용하며, lean-ctx 또는 nushell이 설치되어 있으면 해당 백엔드에 위임합니다. lowfat는 추가적인 선택적 백엔드입니다. lowfat 바이너리를 설치하고 PRECC_LOWFAT=1을 설정하면 PRECC가 적합한 명령어를 lowfat <command>로 감쌉니다. lowfat을 적응형 선택기가 다른 압축 모드들과 비교 측정하여 명령어 클래스별로 선택하는 또 하나의 압축 모드로 취급하는 것입니다. 이 기능은 기본적으로 꺼져 있으며, PRECC_LOWFAT=1이 없으면 아무것도 변경되지 않습니다. lowfat 자체의 Claude Code 후크는 함께 설치하지 마십시오. 둘 다 명령어를 재작성하게 됩니다. precc doctor는 이러한 충돌을 감지하면 경고합니다.

# Install lowfat (separately), then opt in:
export PRECC_LOWFAT=1

단계 6: JSON 출력

수정된 명령을 JSON으로 직렬화하여 stdout에 씁니다. 변경 사항이 없으면 출력은 Claude Code에 원래 명령을 사용하도록 신호를 보냅니다.

성능

전체 파이프라인이 5밀리초(p99) 이내에 완료됩니다. 주요 최적화:

잠금 없는 동시 읽기를 위한 WAL 모드의 SQLite
스킬 매칭을 위한 사전 컴파일된 정규식 패턴
캐시된 파일 시스템 스캔(5초 TTL)
핫 경로에 네트워크 호출 없음
Fail-open: 모든 오류는 원래 명령으로 넘어감

훅 수동 테스트

훅을 직접 호출할 수 있습니다:

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

PRECC User Guide