훅 설정 가이드

Claude Code 프롬프트 수집을 위한 훅 설치 방법

가이드

Claude Code 훅이란?

Claude Code 훅은 특정 이벤트(도구 사용, 세션 종료 등) 발생 시 자동으로 실행되는 스크립트입니다. ax-dashboard 훅을 설치하면 팀원이 Claude Code를 사용할 때마다 프롬프트가 자동으로 수집됩니다.

훅 파일 경로 확인

ax-dashboard 레포를 클론한 위치를 확인하고, 아래에 훅 파일의 절대 경로를 입력하세요.

훅 파일 절대 경로:

터미널에서 경로 확인하기

# ax-dashboard 레포 위치로 이동 후
pwd
# 출력: /Users/YOUR_NAME/projects/ax-dashboard
# 훅 경로: /Users/YOUR_NAME/projects/ax-dashboard/hooks/ax-prompt-hook.js

settings.json 수정

~/.claude/settings.json 파일을 열고 아래 내용을 추가하세요. 기존 settings.json에 hooks 키가 없다면 추가하고, 있다면 병합하세요.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "node /Users/YOUR_NAME/path/to/ax-dashboard/hooks/ax-prompt-hook.js"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "node /Users/YOUR_NAME/path/to/ax-dashboard/hooks/ax-prompt-hook.js"
          }
        ]
      }
    ]
  }
}

기존 hooks 설정이 있다면 덮어쓰지 말고 기존 배열에 추가하세요. PostToolUse 이벤트에 여러 훅을 등록할 수 있습니다.

환경 변수 설정 (선택)

훅 동작을 커스터마이즈하려면 환경 변수를 설정하세요. 설정하지 않아도 기본값으로 동작합니다.

AX_DASHBOARD_URL

대시보드 서버 URL. 배포된 ax-dashboard가 있다면 해당 URL 입력

기본값: http://localhost:3000

AX_USER

팀원 식별자. 설정 안 하면 OS 로그인 이름 사용

기본값: OS 사용자명

AX_PROJECT

프로젝트 이름. 설정 안 하면 cwd 마지막 폴더명 사용

기본값: 현재 디렉토리명

~/.zshrc 또는 ~/.bashrc에 추가:

export AX_DASHBOARD_URL="http://localhost:3000"
export AX_USER="YOUR_GITHUB_ID"
# AX_PROJECT는 프로젝트별로 자동 감지됩니다

Claude Code 재시작

settings.json 변경 사항을 적용하려면 Claude Code를 완전히 종료 후 재시작해야 합니다.

Claude Code 터미널 창 모두 닫기

새 터미널에서 claude 명령 재실행

아무 명령어나 실행해보면 훅이 동작함

연동 테스트

설치가 올바르게 됐는지 확인하려면 아래 테스트 버튼을 눌러 대시보드에 테스트 프롬프트를 전송하세요.

문제 해결

훅이 동작하지 않습니다

→settings.json 경로가 올바른지 확인: ~/.claude/settings.json
→JSON 문법 오류 확인 (쉼표, 따옴표 등)
→node 명령이 PATH에 있는지 확인: which node
→Claude Code 완전 재시작 후 다시 시도

프롬프트가 대시보드에 안 보입니다

→ax-dashboard 서버가 실행 중인지 확인: http://localhost:3000/api/prompts
→AX_DASHBOARD_URL 환경 변수 확인
→훅이 비동기로 동작하므로 1~2초 후 새로고침
→DB가 비어있으면 목업 데이터가 표시됩니다

훅 때문에 Claude Code가 느려졌습니다

→훅은 비동기(fire-and-forget)로 동작해 성능에 영향 없어야 합니다
→대시보드 서버가 과부하 상태면 느려질 수 있으니 서버 로그 확인
→ax-prompt-hook.js의 timeout을 3000ms → 1000ms로 줄여볼 수 있습니다

PostToolUse 말고 다른 이벤트를 캡처하고 싶습니다

→Stop 이벤트: 세션 종료 시 프롬프트 포함 전체 데이터 수신 가능
→PreToolUse: 도구 실행 전 호출, 차단 가능 (exit 2)
→Notification: 알림 발생 시 호출
→claude-settings-snippet.json 파일에 Stop 이벤트 예시 포함

훅 이벤트 레퍼런스

이벤트	발생 시점	stdin 데이터
`PreToolUse`	도구 실행 직전	tool_name, tool_input, session_id
`PostToolUse`	도구 실행 완료 후	tool_name, tool_input, tool_response, session_id
`Stop`	세션 응답 완료 시	prompt, response, session_id, cost
`Notification`	알림 발생 시	message, session_id