hooks를 사용하여 작업 자동화

첫 번째 훅 설정하기

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "f=$(jq -r '.tool_input.file_path') && npx prettier --write --ignore-unknown \"$f\"" }]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" }]
      }
    ]
  }
}

자동화할 수 있는 작업

Claude가 입력을 필요로 할 때 알림 받기

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

osascript -e 'display notification "test"'

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

notify-send 'Claude Code' 'test'

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

편집 후 코드 자동 포맷팅

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "f=$(jq -r '.tool_input.file_path') && npx prettier --write --ignore-unknown \"$f\""
          }
        ]
      }
    ]
  }
}

보호된 파일에 대한 편집 차단

#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Normalize Windows backslash separators so the patterns below match
FILE_PATH="${FILE_PATH//\\//}"

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

chmod +x .claude/hooks/protect-files.sh

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

컨텍스트 압축 후 컨텍스트 재주입

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

구성 변경 감사

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

디렉터리 또는 파일 변경 시 환경 다시 로드

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ],
    "CwdChanged": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": ".envrc|.env",
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

특정 권한 프롬프트 자동 승인

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{hookSpecificOutput: {hookEventName: \"PermissionRequest\", decision: {behavior: \"allow\", updatedInput: .tool_input}}}'"
          }
        ]
      }
    ]
  }
}

"command": "jq -c '{hookSpecificOutput: {hookEventName: \"PermissionRequest\", decision: {behavior: \"allow\", updatedInput: .tool_input, updatedPermissions: [{type: \"setMode\", mode: \"acceptEdits\", destination: \"session\"}]}}}'"

Hooks 작동 방식

• "type": "http": 이벤트 데이터를 URL에 POST합니다. HTTP hooks를 참조하세요.
• "type": "mcp_tool": 구성된 MCP 서버에서 도구를 호출합니다. MCP tool hooks를 참조하세요.
• "type": "prompt": 단일 턴 LLM 평가입니다. 프롬프트 기반 hooks를 참조하세요.
• "type": "agent": 도구 액세스를 통한 다중 턴 검증입니다. Agent hooks는 실험적이며 변경될 수 있습니다. Agent 기반 hooks를 참조하세요.

여러 hooks의 결과 결합

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r .tool_input.command >> ~/.claude/bash.log"
          },
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm-rf.sh"
          }
        ]
      }
    ]
  }
}

입력 읽기 및 출력 반환

Hook 입력

• hook_event_name: hook을 트리거한 이벤트
• tool_name: Claude가 사용하려는 도구
• tool_input: Claude가 도구에 전달한 인수입니다. Bash의 경우 command 필드는 셸 명령을 포함합니다.

{
  "session_id": "abc123",
  "cwd": "/Users/sarah/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

Hook 출력

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  # stderr는 Claude의 피드백이 됩니다
  exit 2 # exit 2 = 작업 차단
fi

exit 0  # exit 0 = 결정 없음; 정상적인 권한 흐름이 적용됩니다

• Exit 0: PreToolUse hook에서 0으로 종료해도 exit 0은 도구 호출을 승인하지 않으므로 도구 호출은 여전히 정상적인 권한 흐름을 거칩니다. UserPromptSubmit, UserPromptExpansion, SessionStart 및 PostModelSwitch hooks의 경우 Claude Code는 일반 텍스트로 처리하는 stdout을 Claude의 컨텍스트에 추가합니다.
• Exit 2: stderr에 이유를 작성합니다. 이벤트에 따라 Claude가 이를 피드백으로 받아 조정하거나, 사용자에게 표시되거나, ConfigChange 및 Elicitation처럼 메시지가 표시되지 않습니다. 일부 이벤트는 차단될 수 없습니다: SessionStart 및 기타의 경우 exit 2는 stderr를 사용자에게 표시하고 실행이 계속됩니다. 전체 목록은 이벤트별 exit 코드 2 동작을 참조하세요.
• 다른 종료 코드: WorktreeCreate가 0이 아닌 모든 종료에서 실패하는 것과 같은 이벤트별 예외는 Exit code output을 참조하세요. 다른 이벤트에서는 해당 hook이 실패 시 작업을 차단하는 hook이 아닌 한, hook이 stdout에 출력한 내용을 기준으로 해당하는 경우를 찾습니다:
  • 스키마 검증을 통과하는 구문 분석된 객체: Claude Code는 종료 코드를 무시하고 JSON만이 결과를 결정하며 hook은 오류로 보고되지 않습니다.
  • 스키마 검증에 실패하는 구문 분석된 객체 또는 Claude Code가 JSON으로 구문 분석하려고 하지만 유효한 JSON이 아닌 stdout: 작업이 차단되지 않는 오류로 진행됩니다. 검증 또는 구문 분석 메시지는 <hook name> hook error 공지에서 확인하세요.
  • Claude Code가 일반 텍스트로 처리하는 stdout 또는 빈 stdout: 작업이 차단되지 않는 오류로 진행됩니다. 트랜스크립트는 <hook name> hook error 공지를 표시한 후 Failed with non-blocking status code:로 접두사가 붙은 stderr의 첫 번째 줄을 표시합니다. 전체 stderr를 캡처하려면 claude --debug를 사용하거나 세션 중에 /debug를 실행하여 디버그 로깅을 활성화하세요.

구조화된 JSON 출력

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

• 네트워크 경로에서의 읽기
• requiresUserInteraction으로 표시된 MCP 도구
• Agent SDK 앱이 always_ask로 표시한 도구에 대한 호출(권한 모드가 해당 호출을 승인하는 경우 제외)
• 해당 설정이 Claude Code에 도달하는 세션에서 조직이 ask로 설정한 커넥터 도구 플랜 모드에서 "allow"가 어떻게 동작하는지는 플랜 모드의 hook 승인을 참조하세요.

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Current branch: release-42. Deploy freeze until Friday."
  }
}

Matchers로 hooks 필터링

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "prettier --write ..." }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "clear",
        "hooks": [
          {
            "type": "command",
            "command": "rm -f /tmp/claude-scratch-*.txt"
          }
        ]
      }
    ]
  }
}

if 필드를 사용하여 도구 이름 및 인수로 필터링

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

Hook 위치 구성

프롬프트 기반 훅

• "ok": true: 작업이 진행됩니다
• "ok": false: 어떤 일이 발생하는지는 이벤트에 따라 다릅니다:
  • Stop 및 SubagentStop: reason이 Claude로 피드백되어 계속 작업하도록 합니다. 단, 응답이 "impossible": true를 설정하여 조건을 절대 만족할 수 없는 것으로 표시하는 경우, Claude Code는 중지를 허용하고 턴이 종료됩니다
  • PreToolUse: 도구 호출이 거부됩니다. 기본적으로 턴이 종료되고 거부 reason이 경고 줄로 채팅에 나타납니다. 훅에서 continueOnBlock: true를 설정하여 대신 reason을 Claude에 도구 오류로 반환하면, Claude가 조정하고 계속할 수 있습니다
  • PostToolUse: 기본적으로 턴이 종료되고 reason이 경고 줄로 채팅에 나타납니다. continueOnBlock: true를 설정하여 reason을 Claude로 피드백하고 대신 턴을 계속합니다
  • PostToolBatch, UserPromptSubmit, 및 UserPromptExpansion: 턴이 종료되고 reason이 경고 줄로 채팅에 나타납니다

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

에이전트 기반 hooks

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

HTTP hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

• 2xx 상태: 도구 호출을 차단하려면 본문에 적절한 hookSpecificOutput 필드를 반환합니다.
• 그 외 모든 상태 또는 요청 실패: Claude Code는 비차단 오류를 보고하고 작업을 계속 진행합니다. 단, 해당 hook이 실패 시 작업을 차단하는 hook인 경우는 제외합니다. 엔드포인트가 실패했을 때 작업을 차단하려면 hook에 onFailure: "block"을 설정합니다.

제한 사항 및 문제 해결

제한 사항

• 명령 hooks는 stdout, stderr 및 종료 코드를 통해서만 통신합니다. / 명령이나 도구 호출을 직접 트리거할 수 없습니다. additionalContext를 통해 반환된 텍스트는 Claude가 일반 텍스트로 읽는 시스템 알림으로 주입됩니다. HTTP hooks는 응답 본문을 통해 통신합니다.
• Hook 타임아웃은 유형에 따라 다릅니다. timeout 필드(초 단위)로 hook당 재정의할 수 있습니다.
  • command, http, mcp_tool: 10분. Claude Code는 UserPromptSubmit, PreModelSwitch 및 PostModelSwitch hooks의 기본값을 30초로 낮추고, MessageDisplay의 경우 10초로 낮춥니다.
  • prompt: 30초.
  • agent: 60초.
  • 모든 유형의 SessionEnd hooks는 1.5초 예산을 공유합니다. 설정에서 더 긴 hook당 timeout을 설정하면 Claude Code는 예산을 일치하도록 올리며, 최대 60초까지입니다.
• PostToolUse hooks는 도구가 이미 실행되었으므로 작업을 취소할 수 없습니다.
• PermissionRequest 훅은 Claude Code가 사용자에게 권한을 요청하려고 할 때, 또는 프롬프트를 표시할 수 없는 호출을 자동으로 거부하려고 할 때 발생합니다. -p 플래그를 사용하는 비대화형 모드에서도 dontAsk 모드가 아닌 경우 여전히 실행되며, 어떤 훅도 결정하지 않고 다른 어떤 것도 응답할 수 없는 호출은 거부됩니다.
• Stop hooks는 작업 완료 시에만이 아니라 Claude가 응답을 완료할 때마다 발생합니다. 사용자 중단 시에는 발생하지 않습니다. API 오류는 대신 StopFailure를 발생시킵니다.
• 여러 PreToolUse hooks가 updatedInput을 반환하여 도구의 입력을 다시 쓸 때, Claude Code는 다시 쓴 내용을 병합하지 않으며 도구가 어떤 다시 쓴 입력으로 실행될지도 보장하지 않습니다. 동일한 도구의 입력을 다시 쓰는 hook이 두 개 이상 있는 것을 피합니다.

Hooks 및 권한 모드

• "allow"보다 우선하는 항목: "allow"를 반환하는 훅은 설정의 거부 규칙을 우회하지 않으며, 다음에 대한 프롬프트를 억제할 수 없습니다:
  • 네트워크 경로에서의 읽기
  • requiresUserInteraction으로 표시된 MCP 도구
  • Agent SDK 앱이 always_ask로 표시한 도구에 대한 호출(권한 모드가 해당 호출을 승인하는 경우는 제외)
  • 해당 설정이 Claude Code에 도달하는 세션에서 조직이 ask로 설정한 커넥터 도구

• 모든 권한 모드에서의 "deny": permissionDecision: "deny"를 반환하는 훅은 bypassPermissions 모드 또는 --dangerously-skip-permissions에서도 도구를 차단합니다. PreToolUse 훅은 dontAsk를 포함한 모든 권한 모드에서 권한 모드 확인 전에 발생합니다. 이를 통해 사용자가 권한 모드를 변경하여 우회할 수 없는 정책을 적용할 수 있습니다.

Hook이 발생하지 않음

• /hooks를 실행하고 hook이 올바른 이벤트 아래에 나타나는지 확인합니다
• 스킬의 frontmatter에 있는 훅의 경우 스킬을 호출하거나 Claude에게 호출하도록 요청한 다음 /hooks를 다시 실행합니다. /hooks는 세션에서 호출되지 않은 스킬의 훅을 나열하지 않습니다. /hooks에 여전히 훅이 나열되지 않으면 구문 분석되지 않은 frontmatter나 스킬 훅의 제한 중 하나와 같은 다른 원인을 확인합니다
• Matcher 패턴이 도구 이름과 정확히 일치하는지 확인합니다. Matchers는 대소문자 구분입니다
• 올바른 이벤트 유형을 트리거하는지 확인합니다: PreToolUse는 도구 실행 전에 발생하고 PostToolUse는 후에 발생합니다. PermissionRequest hook은 Claude Code가 사용자에게 권한을 요청하려고 할 때 발생합니다. 비대화형 경우는 제한 사항을 참조하십시오

출력에 Hook 오류

• 스크립트가 예기치 않게 0이 아닌 코드로 종료되었습니다. 샘플 JSON을 파이프하여 수동으로 테스트합니다:
  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?  # Check the exit code
  
• “command not found”가 표시되면 절대 경로를 사용하거나 ${CLAUDE_PROJECT_DIR}을 사용하여 스크립트를 참조합니다. 셸 인용을 완전히 피하려면 "args": []를 추가하여 exec form으로 전환하면 셸 없이 스크립트를 직접 생성합니다
• “jq: command not found”가 표시되면 jq를 설치하거나 JSON 구문 분석을 위해 Python/Node.js를 사용합니다
• 메시지에 blocking because Git Bash wasn't found가 포함되어 있으면 Windows 환경에서 Claude Code가 Git Bash를 찾지 못했고, 실패하거나 시간 초과된 훅이 도구 호출을 차단한 것입니다. 해결 방법은 Git Bash가 없는 Windows에서 실패한 훅을 참조하십시오
• 공지에 JSON 검증 메시지가 표시되면 hook의 stdout이 JSON으로 구문 분석되었지만 스키마 검증에 실패했습니다. JSON 구문 분석 메시지가 표시되면 stdout이 JSON 객체처럼 보였지만 유효한 JSON이 아니었습니다. 둘 다 종료 0에서도 발생합니다. 구문 분석 실패를 수정하려면 문자열 연결 대신 jq와 같은 JSON 인코더로 페이로드를 빌드하여 값 내의 따옴표와 백슬래시가 이스케이프됩니다. 참조의 Exit code output 섹션에서 종료 코드 및 JSON 조합을 다룹니다
• 스크립트가 실행되지 않으면 실행 가능하게 만듭니다: chmod +x ./my-hook.sh

/hooks에 구성된 hooks가 없음

• 파일 편집은 일반적으로 자동으로 선택됩니다. 몇 초 후에 나타나지 않으면 파일 감시자가 변경을 놓쳤을 수 있습니다: 세션을 다시 시작하여 강제로 다시 로드합니다.
• JSON이 유효한지 확인합니다: 후행 쉼표 및 주석은 허용되지 않습니다
• 설정 파일이 올바른 위치에 있는지 확인합니다: 프로젝트 hooks의 경우 .claude/settings.json, 전역 hooks의 경우 ~/.claude/settings.json
• 메뉴에 Only hooks from managed settings run here가 표시되면 조직에서 allowManagedHooksOnly를 설정한 것입니다. 사용자, 프로젝트 및 로컬 설정 파일의 훅은 실행되지 않으며 목록에 표시되지 않습니다

Stop hook이 블록 상한에 도달함

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Allow Claude to stop
fi
# ... rest of your hook logic

Hook JSON이 효과가 없음

• JSON 앞의 추가 출력: 다른 무언가가 먼저 stdout에 쓰기 때문에(일반적으로 셸 프로필의 무조건적인 echo) 출력이 더 이상 {로 시작하지 않습니다. JSON 앞의 셸 프로필 출력을 참조하십시오.
• 잘못된 수준의 필드: 각 필드의 배치를 JSON output 형식과 비교합니다. 예를 들어 permissionDecision은 최상위 수준이 아니라 hookSpecificOutput 내부에 속합니다. 잘못된 수준의 필드를 참조하십시오.

JSON 앞의 셸 프로필 출력

Shell ready on arm64
{"decision": "block", "reason": "Not allowed"}

# ~/.zshrc 또는 ~/.bashrc에서
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

잘못된 수준의 필드

훅이 수행한 작업 확인

• 성공: 훅의 JSON이 systemMessage 또는 Stop 훅 피드백과 같은 것을 표시하지 않는 한 아무것도 표시되지 않습니다.
  • 훅이 실행되었는지 확인하려면 재포맷된 파일과 같은 효과를 확인합니다
• 차단 오류: 대부분의 이벤트에서는 차단과 함께 전달된 메시지(예: Blocked: rm commands are not allowed)가 표시됩니다. ConfigChange 및 Elicitation과 같은 몇 가지 이벤트에서는 메시지가 표시되지 않습니다. 메시지의 출처는 종료 코드 2에서 다룹니다.
• 차단하지 않는 오류: Failed with non-blocking status code: 뒤에 오는 stderr의 첫 번째 줄이나 JSON 검증 또는 구문 분석 메시지와 같은 간단한 설명과 함께 <hook name> hook error 공지가 표시됩니다. 작업은 계속 진행되었습니다.

자세히 알아보기

• Hooks 참조: 전체 이벤트 스키마, JSON 출력 형식, 비동기 hooks 및 MCP 도구 hooks
• 보안 고려 사항: 공유 또는 프로덕션 환경에서 hooks를 배포하기 전에 검토합니다
• Bash 명령 검증기 예제: 완전한 참조 구현