Cmd. /hooks
도구 이벤트별로 구성된 훅(이벤트·개수·매처·핸들러)을 한눈에 보여주는 읽기 전용 뷰어. 훅 추가·수정·삭제는 설정 JSON을 직접 편집하거나 Claude에게 요청해야 합니다.
핵심 요약
- hook 설정·event 확인
- 입력 위치·지원 조건을 확인한 뒤 아래 실행 예를 사용합니다.
역할
hook 설정·event 확인
/hooks사용 조건
| 항목 | 기준 |
|---|---|
| 입력 위치 | 실행 중인 CLI의 입력창 |
| 종류 | 내장 명령 |
| 상태 | 현재 공식 표 |
| 별칭 | — |
| 공식 최소 버전 | 명시되지 않음 |
| 검증 기준 | 2026-09-22 · Claude Code 2.1.278 |
설치본의 명령 메뉴와 계정·조직 설정에 따라 사용할 수 있는 항목이 달라집니다.
사용 예
/hooks/hooks는 인자를 받지 않습니다. 실행하면 구성된 훅을 이벤트별로 나열한 읽기 전용 메뉴가 열립니다.
선택 시점
- 현재 어떤 이벤트에 어떤 훅이 걸려 있는지 한눈에 점검
- 매처가 의도한 도구(예:
Bash,Edit|Write,mcp__memory__.*)에만 매칭되는지 확인 - command/HTTP/prompt 핸들러의 실제 설정값과 URL 검토
InstructionsLoaded훅으로 CLAUDE.md 로드 시 커스텀 동작 실행 (v2.1.69)- HTTP hooks로 외부 URL에 JSON POST하고 JSON 응답 수신 (v2.1.63) — 비-2xx·연결 실패·타임아웃은 비차단 에러로 처리되어 실행을 계속합니다
TeammateIdle/TaskCompletedhooks에서{"continue": false, "stopReason": "..."}응답으로 작업 중단 제어 (v2.1.69)
관련 명령 선택
| 명령어 | 차이점 | 언제 선택 |
|---|---|---|
/hooks | 훅 설정 조회(읽기 전용) | 자동화 구성 점검 |
/permissions | 실행 권한 정책 관리 | 안전 가드레일 |
/config | 테마·모델 등 설정 편집 | 일반 환경 설정 |
실행 결과와 유지 범위
구성된 훅과 실행 조건을 확인합니다. 훅을 수정하면 해당 이벤트에서 실행되는 동작이 달라집니다.
공식 문서의 정의는 "도구 이벤트에 대한 훅 설정을 조회한다(View hook configurations for tool events)"입니다.
/hooks는 읽기 전용 뷰어입니다. 현재 구성된 훅 이벤트와 각 이벤트에 걸린 훅 개수, 매처(matcher), 각 핸들러의 상세(command·prompt·URL)를 보여줍니다.
이 메뉴에서 훅을 추가·수정·삭제할 수는 없습니다. 훅을 실제로 바꾸려면 설정 JSON 파일(.claude/settings.json 등)을 직접 편집하거나 Claude에게 수정을 요청해야 합니다.
훅 자체는 Claude Code 수명주기의 특정 시점에 자동 실행되는 사용자 정의 셸 명령·HTTP 엔드포인트·LLM 프롬프트입니다. stdin(command 훅)이나 POST 본문(HTTP 훅)으로 JSON 컨텍스트를 받고, 동작을 차단·허용하는 결정을 돌려줍니다.
주의사항
/hooks는 조회 전용이므로, 훅을 바꾸려면 설정 JSON을 편집하거나 Claude에게 수정을 요청해야 합니다.- 자동화 실패 시 수동 fallback 경로를 문서화하고, 훅 실행 비용·시간을 모니터링하세요.
PreToolUse훅은hookSpecificOutput.permissionDecision으로 도구 실행을 제어합니다 —allow(승인),deny(차단),ask(사용자 확인),defer(기본 권한 흐름 적용).
v2.1.74: SessionEnd 훅 타임아웃 수정
이전 버전에서는 SessionEnd 훅이 hook.timeout 설정과 무관하게 종료 시 1.5초 후 강제 종료되었습니다.
v2.1.74부터 환경변수 CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS로 타임아웃을 직접 설정할 수 있습니다.
# 예: SessionEnd 훅에 10초 여유 부여
export CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=10000세션 종료 시 로그 전송이나 정리 스크립트처럼 시간이 걸리는 훅을 운영한다면 반드시 설정하세요.
공식 근거
전체 명령 목록 · 검증 범위 · 이 명령의 변경 기록