비동기 실행 async:true — 훅을 기다리지 않기

async: true는 훅을 백그라운드에서 실행해, 처리 완료를 기다리지 않고 바로 다음 작업에 착수할 수 있게 하는 Hooks 옵션입니다. 2026년 1월 하순에 추가된 이 옵션을 쓰면 시간이 걸리는 훅 처리가 더 이상 작업의 병목이 되지 않습니다.

Hooks 매처로 훅의 발화 조건을 정했다면, 이번에는 발화한 훅이 작업 흐름을 막지 않게 하는 방법입니다.

핵심 요약

• async: true를 훅 설정에 추가하기만 하면 비동기 실행이 유효해집니다.
• 훅 완료를 기다리지 않고 다음 프롬프트를 전송할 수 있습니다.
• "결과를 기다릴 필요가 없는 처리"(포맷, 알림, 환경 구축 등)에 최적입니다.

동기 훅과 비동기 훅은 무엇이 다른가

통상 훅은 동기적으로 실행됩니다. 즉 훅 처리가 완료될 때까지 Claude Code는 다음 조작을 받지 않습니다. 안전성 관점에서는 올바른 동작이지만, 처리 시간이 길면 그만큼 대기 시간이 생깁니다.

한편 async: true를 지정하면 훅이 백그라운드에서 실행됩니다. 훅 완료를 기다리지 않고 바로 다음 프롬프트를 전송할 수 있습니다.

설정 방법 — 한 줄만 추가하면 된다

훅 설정에 "async": true를 추가하기만 하면 됩니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "./format-code.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

동작은 어떻게 확인하나

아래 설정에서는 동기 훅이 즉시 실행된 뒤, 비동기 훅이 10초 후에 백그라운드에서 완료됩니다. $CLAUDE_PROJECT_DIR은 Hooks 환경 변수에서 다룬 프로젝트 루트 경로입니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"⚡ 동기 훅 실행: $(date '+%H:%M:%S')\" >> $CLAUDE_PROJECT_DIR/async-test.log"
          },
          {
            "type": "command",
            "command": "sleep 10 && echo \"✅ 비동기 훅 완료: $(date '+%H:%M:%S')\" >> $CLAUDE_PROJECT_DIR/async-test.log",
            "async": true
          }
        ]
      }
    ]
  }
}

이 설정으로 파일을 편집하면 async-test.log에 아래처럼 기록됩니다.

⚡ 동기 훅 실행: 11:21:05
✅ 비동기 훅 완료: 11:21:15

포인트는 10초 대기하는 비동기 훅이 도는 중에도 Claude Code에 다음 프롬프트를 보내는 것이 막히지 않는다는 점입니다. 콘솔에서 직접 시험해 보면, 비동기 훅의 처리 완료를 기다리는 동안에도 추가 프롬프트를 전송할 수 있습니다. 즉 뒤에서 Hooks 처리가 돌아가는 동안에도 작업을 계속할 수 있습니다.

비동기 훅은 어디에 쓰면 좋은가

코드 자동 정형

파일 편집 후에 Prettier나 ESLint를 실행하는 경우, 정형 처리 완료를 기다리지 않고 다음 작업으로 나아갈 수 있는 것은 큰 장점입니다. 자동 포맷 훅의 기본 설정은 PreToolUse·PostToolUse 훅을 참고하세요.

{
  "type": "command",
  "command": "npx prettier --write $CLAUDE_FILE_PATHS",
  "async": true
}

이처럼 Claude Code에서 하고 싶은 다음 작업과 직접 관련되지 않는 처리는 비동기 훅으로 실행하면 편리합니다.

로그 수집·알림

조작 로그를 외부 서비스에 전송하거나 Slack에 알림을 보내는 처리는 결과를 기다릴 필요가 없으므로 비동기 실행에 최적입니다. 완료 알림 훅 자체는 Stop 훅에서 다룹니다.

{
  "type": "command",
  "command": "curl -X POST https://your-webhook.example.com -d \"event=file_edited\"",
  "async": true
}

SessionStart에서의 환경 구축

npm install이나 Docker 컨테이너 기동은 시간이 걸리는 경우가 있지만, 완료를 기다리지 않고 바로 작업을 시작할 수 있으면 편리합니다. SessionStart 훅의 초기화 처리를 비동기로 돌리는 예입니다.

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm install && docker-compose up -d",
            "async": true
          }
        ]
      }
    ]
  }
}

다만 Claude Code에 바로 테스트 실행이나 동작 확인을 시키고 싶을 때는 이야기가 다릅니다. 환경 구축이 끝나기 전에 테스트를 돌리면 실패하므로, 그런 경우에는 동기로 두는 편이 안전합니다. 코드 편집부터 시작하는 경우에만 뒤에서 진행하는 것이 좋습니다.

정리

• async: true를 훅 설정에 추가하기만 하면 비동기 실행이 유효해집니다.
• 훅 완료를 기다리지 않고 다음 프롬프트를 전송할 수 있게 됩니다.
• 로그 수집, 알림, 환경 구축 등 "뒤에서 돌아가면 되는 처리"에 최적입니다.
• 결과가 다음 작업에 필요한 처리(환경 구축 직후 테스트 등)는 동기로 둡니다.
• 훅의 처리 시간이 병목이 되고 있다면 꼭 시험해 보세요. 서브에이전트 완료 시점에 처리를 거는 방법은 SubagentStop 훅에서 이어집니다.