Hook API

Claude Code Hook 시스템과 Notifier 플러그인이 사용하는 Hook들.

Claude Code Hooks 개요

Claude Code는 특정 이벤트 발생 시 사용자 정의 스크립트를 실행할 수 있다.

사용 가능한 Hook

Hook	발생 시점	용도
UserPromptSubmit	사용자가 프롬프트 입력 시	시간 기록, 로깅
Stop	Claude 응답 완료 시	작업 완료 알림
Notification	권한 요청, 대기 상태 시	즉시 알림
SessionEnd	세션 종료 시	정리 작업

hooks.json 구조

{
  "hooks": {
    "HookName": [
      {
        "matcher": "optional_matcher",
        "hooks": [
          {
            "type": "command",
            "command": "스크립트 경로"
          }
        ]
      }
    ]
  }
}

필드 설명

필드	필수	설명
matcher	아니오	이벤트 필터링 (Notification Hook에서 사용)
type	예	항상 "command"
command	예	실행할 스크립트 경로

Notifier가 사용하는 Hook

UserPromptSubmit

사용자 입력 시 타임스탬프를 저장한다.

{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/save-prompt.sh"
      }]
    }]
  }
}

save-prompt.sh 동작:

# 현재 시간을 파일에 저장
date +%s > "$DATA_DIR/timestamp-${SESSION_ID}.txt"

Stop

Claude 응답 완료 시 알림을 보낸다.

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/notify.sh"
      }]
    }]
  }
}

notify.sh 동작:

1. 저장된 타임스탬프와 현재 시간 비교
2. 설정된 최소 시간(기본 20초) 이상이면 알림 전송

Notification

권한 요청 또는 대기 상태 시 즉시 알림을 보낸다.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [{
          "type": "command",
          "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/notify.sh"
        }]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [{
          "type": "command",
          "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/notify.sh"
        }]
      }
    ]
  }
}

matcher 값:

matcher	설명
permission_prompt	파일 생성, 명령 실행 등 권한 요청
idle_prompt	사용자 입력 대기

SessionEnd

세션 종료 시 임시 파일을 정리한다.

{
  "hooks": {
    "SessionEnd": [{
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/cleanup-session.sh"
      }]
    }]
  }
}

환경변수

Hook 스크립트에서 사용 가능한 환경변수:

변수	설명
CLAUDE_PLUGIN_ROOT	플러그인 루트 경로
SESSION_ID	현재 세션 ID
NOTIFICATION_TYPE	알림 타입 (Notification Hook)

전체 hooks.json 예시

{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/save-prompt.sh"
      }]
    }],
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/notify.sh"
      }]
    }],
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [{
          "type": "command",
          "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/notify.sh"
        }]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [{
          "type": "command",
          "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/notify.sh"
        }]
      }
    ],
    "SessionEnd": [{
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/cleanup-session.sh"
      }]
    }]
  }
}