Hooks 설정 방법 — settings.json과 /hooks

Hooks 설정은 settings.json의 hooks 항목에 이벤트명·matcher·command 세 요소를 적어 넣는 작업입니다. 훅 개요에서 "훅은 부탁이 아니라 규칙"이라는 개념을 익혔다면, 이 글에서는 그 규칙을 실제로 파일에 적고 동작을 확인하는 방법을 다룹니다. 처음 훅을 쓰는 분이 가장 막히는 지점이 "settings.json을 어떻게 써야 하나"이므로, 간단한 echo로 동작을 확인하는 데까지를 한 번에 따라갑니다.

핵심 요약

• /hooks 커맨드로 현재 설정된 훅 내용을 확인할 수 있습니다(읽기 전용).
• settings.json의 기본 구조는 이벤트명·matcher·command 3요소입니다.
• 명령을 sh 파일로 떼어내면 JSON 이스케이프의 복잡함을 피할 수 있습니다.
• 먼저 간단한 echo로 동작을 확인한 뒤 복잡한 처리로 나아가는 것이 안전합니다.

settings.json의 기본 구조

훅은 settings.json의 hooks 프로퍼티에 기술합니다. 파일 자체의 위치와 우선순위는 settings.json 설정을 참고하세요.

{
  "hooks": {
    "이벤트명": [
      {
        "matcher": "매처 패턴",
        "hooks": [
          {
            "type": "command",
            "command": "실행할 명령",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

각 필드의 역할은 다음과 같습니다.

매처 패턴의 세부 규칙은 Hooks 매처에서 따로 다룹니다.

/hooks 커맨드로 무엇을 확인할 수 있나

Claude Code 안에서 /hooks를 실행하면 이벤트마다 설정된 훅 개수가 목록으로 표시됩니다. 이벤트를 선택하면 매처 단위로 들어갈 수 있고, 핸들러 상세(이벤트·매처·타입·소스 파일·명령)까지 볼 수 있습니다.

> /hooks
╭───────────────────────────────────────────────────────────────────────────╮
│ Hook Configuration                                                        │
│                                                                           │
│ Hooks are shell commands you can register to run during Claude Code       │
│ processing. Docs                                                          │
│                                                                           │
│ • Each hook event has its own input and output behavior                   │
│ • Multiple hooks can be registered per event, executed in parallel        │
│ • Direct edits to hooks in settings files are normally picked up          │
│   automatically                                                           │
│ • Default timeout: 600s (command/http/mcp_tool), 30s (prompt), 60s (agent)│
│                                                                           │
│ ⚠ Hooks execute shell commands with your full user permissions. This can  │
│   pose security risks, so only use hooks from trusted sources.            │
│ Learn more: https://code.claude.com/docs/en/hooks                         │
│                                                                           │
│ Configured hook events:                                                   │
│ ❯ PreToolUse           2 hooks configured                                 │
│   PostToolUse          1 hook configured                                  │
│   PostToolUseFailure   0 hooks configured                                 │
│   Notification         0 hooks configured                                 │
│ ↓ UserPromptSubmit     0 hooks configured                                 │
╰───────────────────────────────────────────────────────────────────────────╯
   Enter to view details · Esc to exit

다만 이 메뉴는 읽기 전용입니다. 훅을 추가·변경·삭제하려면 settings.json을 직접 편집하거나, Claude Code에 "이런 훅을 추가해 줘"라고 부탁해 고치게 해야 합니다. 개요만 파악해 두면 나머지는 Claude Code에 맡길 수도 있으니, 먼저 이 글로 구조를 이해해 두는 것이 좋습니다.

명령을 sh 파일로 떼어내는 이유

훅에서 실행할 명령은 settings.json의 command 필드에 직접 적을 수도 있습니다.

"command": "실행할 명령",

하지만 명령이 조금만 복잡해져도 JSON 안에서 따옴표와 특수문자를 이스케이프하는 일이 힘들어집니다. 그래서 명령을 sh 파일로 떼어내고 settings.json에서는 그 파일만 호출하는 방식을 권장합니다. 여기서는 셸 스크립트를 예로 들지만 Python이나 Node.js 스크립트로도 같은 방식으로 설정할 수 있습니다.

sh 파일화의 장점은 세 가지입니다.

• 가독성: 주석을 자유롭게 쓸 수 있고 여러 줄에 걸친 처리도 보기 좋습니다.
• 테스트 용이성: 파일 단독으로 실행할 수 있어 훅을 거치지 않고 직접 동작을 확인할 수 있습니다.
• 재사용성: 같은 스크립트를 여러 이벤트에서 호출하거나 다른 프로젝트에 돌려쓸 수 있습니다.

관리할 파일이 늘어난다는 단점은 있지만, 설정이 복잡해질수록 장점이 커지므로 트레이드오프를 보고 선택하면 됩니다.

첫 훅 만들기 — echo 로 동작 확인

가장 단순한 예로 훅이 실제로 실행되는지 확인해 봅니다. 파일을 만들거나 편집한 뒤에 로그 한 줄을 남기는 훅입니다.

1. 테스트용 폴더 구조를 만듭니다.

mkdir -p ~/Desktop/hooks-test/.claude/hooks   # .claude/hooks 디렉터리 생성
cd ~/Desktop/hooks-test                         # 디렉터리로 이동
touch ~/Desktop/hooks-test/.claude/settings.json  # settings.json 생성

1. settings.json에 아래 설정을 추가합니다. Write 또는 Edit 도구가 실행된 뒤에 hello.sh가 실행됩니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "~/Desktop/hooks-test/.claude/hooks/hello.sh"
          }
        ]
      }
    ]
  }
}

1. hooks 디렉터리 안에 최소한의 sh 파일을 만듭니다. 메시지 한 줄을 hooks.log에 써넣기만 하는 스크립트입니다.

#!/bin/bash
# ~/Desktop/hooks-test/.claude/hooks/hello.sh
echo "Hooks 가 실행됐습니다!" >> ~/Desktop/hooks-test/hooks.log

1. sh 파일에 실행 권한을 부여합니다. 이 단계를 빼먹는 실수가 가장 흔합니다.

chmod +x .claude/hooks/hello.sh

최종 폴더 구조는 다음과 같습니다.

~/Desktop/hooks-test/
└── .claude/
    ├── settings.json    # Hooks 설정
    └── hooks/
        └── hello.sh     # 실행되는 스크립트

1. ~/Desktop/hooks-test 디렉터리에서 Claude Code를 실행하고, 파일을 하나 만들어 달라고 요청합니다. 파일을 만들거나 편집하기만 하면 됩니다.

claude

> test.txt 라는 파일을 만들어 주세요.

1. hooks.log가 생성되어 있으면 훅이 실행된 것입니다.

cat ~/Desktop/hooks-test/hooks.log
# Hooks 가 실행됐습니다!

이렇게 간단한 echo로 먼저 동작을 확인한 뒤 복잡한 처리로 나아가세요. 실전적인 활용 예는 PreToolUse·PostToolUse 훅에서 이어집니다.

훅 에러 메시지가 뜨면 어디를 보나

훅에서 실행할 스크립트 지정이 틀리면 아래 같은 메시지가 표시됩니다.

  ⎿  PostToolUse:Write hook error

어디에 문제가 있는지까지는 알려주지 않으므로, 다음 순서로 확인합니다.

1. 파일 경로가 맞는지 확인합니다. 특히 상대 경로를 지정한 실수가 많습니다.
2. 스크립트에 실행 권한(chmod +x)이 있는지 확인합니다.
3. 스크립트를 터미널에서 직접 실행해 에러가 나는지 확인합니다.
4. 에러가 나지 않으면 settings.json 작성법을 다시 확인합니다.

스크립트 실행 자체는 성공했더라도 종료 코드가 0이 아니면 같은 hook error 메시지가 표시됩니다. 종료 코드가 Claude Code의 동작에 어떤 영향을 주는지는 종료 코드로 제어에서 다룹니다.

정리

• /hooks 커맨드는 현재 설정된 훅을 확인하는 읽기 전용 메뉴입니다.
• settings.json의 훅 구조는 이벤트명·matcher·command 세 요소입니다.
• 명령은 sh 파일로 떼어내면 읽기 쉽고 테스트와 재사용이 편해집니다.
• 간단한 echo 로그로 동작을 확인한 뒤 복잡한 처리로 나아가세요.
• 다음으로는 세션이 시작될 때 초기화를 자동으로 실행하는 SessionStart 훅을 만들어 봅니다.