클로드 코드 훅 2개, 알림부터 자동 검사까지 설정하는 방법 (2026)

3줄 요약

• settings.json에 훅 두 개를 넣어 작업 종료 알림과 파일 수정 후 자동 검사를 받는 절차를 배운다
• /hooks 입력 시 Notification 1개, PostToolUse 1개로 표시되면 두 훅 모두 정상 등록된 것이다
• 훅은 셸이 그대로 실행하므로 PreToolUse deny 훅은 권한 스킵 옵션을 켜도 막는다

터미널에서 클로드 코드 작업이 끝나도 알림이 없어 화면만 쳐다보는 경우가 있다. 클로드 코드 훅은 설정 파일에 이벤트 이름과 셸 명령을 적어두면, 그 시점이 될 때마다 명령이 자동으로 실행되는 기능이다. 설정을 넣은 뒤 클로드 코드 안에서 /hooks를 입력하면 등록된 훅 개수가 바로 뜬다. 이 글은 2026년 9월 11일에 공식 Hooks 문서를 확인한 기준으로 쓴다.

훅이 뭔지, 이 글에서 뭘 할 수 있는지

훅(Hook)은 클로드 코드가 정해진 시점에 자동으로 돌리는 셸 명령이다. 공식 문서는 이런 시점을 여러 이벤트 이름으로 정의한다. 이름만 봐도 뜻이 짐작되는 것들도 있는데, 도구를 부르기 전에 개입하는 PreToolUse, 도구 실행이 끝난 뒤 돌아가는 PostToolUse, 클로드가 알림을 보낼 때 걸리는 Notification 같은 것들이다.

여기서는 그중 둘만 다룬다. 작업이 끝났을 때 알려주는 것 하나, 파일을 고친 뒤 자동으로 검사를 돌리는 것 하나다. 두 개를 설정 파일 하나에 같이 넣는 순서까지 따라가면 이 글이 끝난다.

시작하기 전에 확인할 것

준비물은 2개다. 첫째, 클로드 코드가 설치돼 있어야 한다. 터미널에 claude --version을 치면 숫자가 나온다. 둘째, 아래 예시는 macOS 명령(osascript)을 쓰므로 맥 사용자 기준으로 진행한다. 터미널을 처음 켰다면 클로드 코드 시작 가이드에서 터미널 여는 법부터 확인해도 된다.

두 번째 예시에는 jq라는 프로그램이 하나 더 필요한데, 설치 명령은 해당 부분에서 같이 안내한다.

훅 설정은 어느 파일에 적나

클로드 코드는 설정 파일을 세 위치에서 읽는다. 공식 문서가 정리한 범위는 다음과 같다.

볼 곳: Configure hook location

파일 경로	적용 범위	공유 여부
~/.claude/settings.json	이 컴퓨터의 모든 프로젝트	아니오, 내 컴퓨터에만 있음
.claude/settings.json	지금 열어둔 프로젝트 하나	예, 저장소에 커밋 가능
.claude/settings.local.json	지금 열어둔 프로젝트 하나	아니오, 커밋 대상에서 제외됨

이 글은 첫 번째, ~/.claude/settings.json 기준으로 진행한다. 터미널에서 아래처럼 열면 된다.

mkdir -p ~/.claude
open -e ~/.claude/settings.json

파일이 없으면 새로 만들어지고, 있으면 기존 내용이 열린다. 클로드 코드 CLAUDE.md 가이드에서 다루는 지침 파일과는 저장 위치는 같아도 역할이 다르다. CLAUDE.md는 클로드에게 읽히는 글이고, settings.json의 훅은 셸이 실제로 실행하는 명령이다.

작업이 끝났을 때 알림 받기

파일 안에 아래 내용을 그대로 넣는다. 공식 예시 원문이다.

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

저장한 뒤 클로드 코드에게 아무 작업이나 시키고 기다려본다. [알림: Claude Code needs your attention] 팝업이 화면에 뜨면 성공이다. 다만 이건 소리가 아니라 화면에 뜨는 알림이다. 실제로 소리까지 울리는지는 맥의 알림 설정(무음 모드 여부 등)에 달려 있고, 이 컴퓨터에서 소리 재생 여부까지는 확인하지 못했다. 알림 문구를 바꾸고 싶으면 display notification 뒤 따옴표 안 문장만 고치면 된다.

파일을 고친 뒤 자동으로 검사 돌리기

두 번째 훅은 클로드 코드가 파일을 수정할 때마다 포맷 검사를 돌린다. jq(제이큐, JSON 텍스트를 다루는 명령줄 도구)가 먼저 있어야 하는데, 맥에서는 아래 명령으로 설치한다.

brew install jq

그다음 같은 settings.json 안, Notification 블록 옆에 아래를 추가한다. 역시 공식 예시 그대로다.

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

matcher는 어떤 도구 다음에 이 훅을 돌릴지 정하는 값이다. Edit|Write는 파일을 고치거나(Edit) 새로 쓰는(Write) 도구 뒤에만 실행하라는 뜻이다. npx prettier는 로컬에 Prettier(프리티어, 코드 포맷 도구)가 설치돼 있어야 동작한다. Prettier가 없는 프로젝트라면 이 훅은 오류만 내고 다른 작업은 막지 않는다.

훅이 실제로 등록됐는지 확인하기

저장한 뒤 클로드 코드 안에서 /hooks를 입력한다. 공식 문서에 따르면 이벤트 목록과 함께 이벤트마다 등록된 훅 개수가 표시된다. [Notification: 1], [PostToolUse: 1]처럼 숫자가 보이면 두 훅 모두 붙은 것이다.

숫자가 0이면 JSON 문법이 깨졌을 확률이 높다. 흔한 원인은 마지막 항목 뒤에 쉼표(,)를 하나 더 붙이는 실수다. 같은 이벤트에 훅을 여러 개 넣어도 문제는 없다. 공식 문서는 여러 훅이 같은 이벤트에 걸리면 전부 실행을 마친 뒤 결과를 합친다고 설명한다.

훅을 쓸 때 조심할 점

훅에 적은 명령은 클로드가 아니라 셸이 그대로 실행한다. 그래서 잘못 적은 명령도 진짜로 실행된다. 공식 문서는 PreToolUse 훅이 권한 모드 확인보다 먼저 개입하며, 훅이 deny(거부)로 판정하면 --dangerously-skip-permissions를 켜둔 상태에서도 그 도구 실행을 막는다고 밝힌다. 이번 글에서 다룬 두 훅(Notification, PostToolUse)은 권한을 판단하는 종류가 아니지만, 셸 명령이라는 성격 자체는 같다. 공식 문서에는 보안 주의사항을 다루는 별도 섹션 링크도 있으니, 다른 사람과 공유하는 프로젝트에 훅을 넣기 전에는 그 부분을 한 번 더 열어보는 게 안전하다.

이 글에 나온 말 정리

용어	뜻
훅(Hook)	정해진 시점에 클로드 코드가 자동 실행하는 셸 명령
matcher	어떤 도구 다음에 훅을 돌릴지 정하는 값
Notification	클로드가 알림을 보낼 때 걸리는 이벤트
PostToolUse	도구 실행이 끝난 뒤 걸리는 이벤트
settings.json	훅을 적어두는 설정 파일
jq	JSON 텍스트를 다루는 명령줄 도구

클로드 코드 스킬 가이드에서 다루는 스킬은 클로드에게 지시문과 실행 절차를 추가로 주는 기능이고, 훅은 그와 달리 셸 명령을 강제로 실행시키는 쪽이라 역할이 다르다.

오늘 해야 할 일

1. ~/.claude/settings.json을 열거나 새로 만든다
2. Notification 훅 JSON을 붙여넣는다
3. PostToolUse 훅 JSON을 같은 파일에 추가한다
4. /hooks로 두 훅이 등록됐는지 숫자로 확인한다

검증 기준

• 마지막 업데이트일: 2026-09-11
• 확인 환경: macOS 기준 공식 문서 원문 대조. Notification·PostToolUse 훅을 실제로 실행해 소리·화면 결과를 캡처하는 절차는 이 글에서 수행하지 못했다.
• 주요 근거: Hooks reference, Automate actions with hooks, Settings precedence