Mac에서 Claude Code의 작업 완료 알림과 확인 요청 알림을 받으세요.

Claude Code의 기본 제공 알림은 Claude가 작업을 마치거나 권한 요청으로 일시 정지했을 때, 사용자가 터미널을 떠나 있는 것으로 보이면 발생합니다. 이 알림이 배너로 표시되는지는 터미널 앱에 따라 다릅니다.

Claude Code에는 이를 위한 설정인 preferredNotifChannel이 있습니다. Claude Code에서 /config를 입력하고 Local notifications를 여세요. 기본값은 auto입니다. 그 밖에 terminal_bell, iterm2, iterm2_with_bell, kitty, ghostty, notifications_disabled를 선택할 수 있습니다.

터미널 벨은 프로그램이 사용자의 주의를 요청할 때 터미널에서 내는 짧은 소리나 화면 깜박임입니다. Terminal.app, Warp, VS Code에서 사용하려면 ~/.claude/settings.json 같은 Claude Code 설정 파일의 가장 바깥쪽 중괄호 안에 다음 줄을 추가하는 방법도 있습니다.

"preferredNotifChannel": "terminal_bell"

• iTerm2: Settings > Profiles > Terminal을 열고 Notification Center Alerts를 선택하세요. Filter Alerts를 클릭하고 Send escape sequence-generated alerts를 켜세요.
• Terminal.app: 벨 알림을 더 쉽게 알아보려면 Settings > Profiles > Advanced를 여세요. Bell에서 Terminal이 백그라운드에 있을 때 Dock 아이콘에 배지를 표시하거나 아이콘을 튀어 오르게 하는 옵션을 선택하세요. Claude Code를 처음 실행할 때 터미널 설정을 수락했다면 Terminal의 Audible bell이 꺼져 있습니다. 소리를 들으려면 같은 곳에서 Audible bell을 선택하세요.
• 모든 터미널: 시스템 설정 > 알림에서 터미널 앱 자체에 알림 권한을 부여해야 합니다.

이전 글에서는 claude config set을 실행하라고 안내합니다. 이 명령은 더 이상 존재하지 않습니다. /config를 사용하거나 설정 파일을 수정하세요.

훅은 Claude Code가 정해진 시점에 실행하는 셸 명령입니다. 설정 파일에 사용할 훅을 등록합니다. 터미널이 훅 실행에 관여하지 않으므로 모든 터미널에서 작동합니다.

Anthropic의 공식 알림 설정 예제는 Notification 이벤트를 사용합니다. 이 이벤트는 idle_prompt를 통해서만 Claude의 작업 완료를 알립니다. 완료 후 약 60초가 지나야 하며, 그동안 사용자가 아무것도 입력하지 않았을 때만 알립니다. Claude가 멈추는 즉시 알림을 받으려면 Stop을 사용하세요.

요청 한도 초과 같은 API 오류로 턴이 끝나면 Stop 대신 StopFailure가 발생합니다. Notification 훅은 어떤 동작도 차단할 수 없으며, 지정한 명령만 실행합니다.

아래 코드 조각은 모두 ~/.claude/settings.json에 넣습니다. 이 파일은 모든 프로젝트에 적용됩니다. 각 코드 조각은 JSON 및 셸 구문 검증을 마쳤으며, 추가 소프트웨어가 필요하지 않습니다.

Claude가 작업을 마치면 Mac 배너로 알립니다.

~/.claude/settings.json에 추가

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'on run argv' -e 'display notification (item 1 of argv) with title \"Claude Code\" sound name \"Glass\"' -e 'end run' \"Finished in ${PWD##*/}\""
          }
        ]
      }
    ]
  }
}

Claude가 승인을 기다리면 Mac 배너로 알립니다.

~/.claude/settings.json에 추가

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt|elicitation_dialog|elicitation_url_dialog",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'on run argv' -e 'display notification (item 1 of argv) with title \"Claude Code needs you\" sound name \"Ping\"' -e 'end run' \"Waiting for your OK in ${PWD##*/}\""
          }
        ]
      }
    ]
  }
}

두 배너 모두 세션이 실행 중인 폴더 이름을 표시합니다.

스크립트 편집기의 배너 표시를 허용하세요.

Mac에서 osascript 배너는 기본 내장 앱인 스크립트 편집기를 통해 표시됩니다. 스크립트 편집기에 알림을 허용하기 전에는 명령이 아무런 오류 표시 없이 실패하며, macOS도 권한을 요청하지 않습니다.

1. Terminal에서 다음 명령을 한 번 실행하세요.

osascript -e 'display notification "test"'

2. 시스템 설정 > 알림을 열고 스크립트 편집기를 찾아 알림 허용을 켜세요.

배너 대신 소리로 알립니다.

~/.claude/settings.json에 추가

{
  "hooks": {
    "Stop": [
      { "hooks": [ { "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" } ] }
    ],
    "Notification": [
      { "matcher": "permission_prompt", "hooks": [ { "type": "command", "command": "afplay /System/Library/Sounds/Ping.aiff" } ] }
    ]
  }
}

음성으로 알립니다.

~/.claude/settings.json에 추가

{
  "hooks": {
    "Stop": [
      { "hooks": [ { "type": "command", "command": "say \"Claude has finished\"", "async": true } ] }
    ],
    "Notification": [
      { "matcher": "permission_prompt", "hooks": [ { "type": "command", "command": "say \"Claude needs your permission\"", "async": true } ] }
    ]
  }
}

"async": true를 사용하면 Mac이 음성으로 알리는 동안에도 Claude Code가 계속 작업할 수 있습니다.

한 이벤트는 배너로, 다른 이벤트는 소리로 알리려면 알림 훅 생성기를 두 번 사용하세요. 매번 이벤트 하나와 알림 방식을 선택한 다음, 병합 입력란에서 두 결과를 모두 파일에 추가하세요. 생성기는 각 코드 조각을 어느 파일에 넣어야 하는지 알려 주며, 모든 처리는 브라우저 안에서 이루어집니다.

• 폴더를 신뢰하도록 허용하세요. 해당 폴더의 작업 공간 신뢰 대화상자에서 동의하기 전까지 Claude Code는 모든 훅의 실행을 보류합니다. ~/.claude/settings.json에 있는 훅도 포함됩니다.
• 불러온 훅을 확인하세요. Claude Code에서 /hooks를 입력하세요. 훅 목록과 각 훅이 정의된 파일을 보여 주지만, 여기서 훅을 추가할 수는 없습니다. Claude Code는 보통 수정 사항을 자동으로 반영합니다. 반영되지 않으면 세션을 다시 시작하세요.
• 업무용 Mac을 사용한다면. 조직에서 직접 관리하는 훅만 허용할 수 있습니다. 이 경우 /hooks에 ‘Only hooks from managed settings run here’가 표시되며, 개인 훅은 실행되지 않습니다.
• 알림이 두 개씩 온다면. 모든 설정 수준의 훅이 함께 적용됩니다. 따라서 프로젝트 파일의 알림 훅과 사용자 파일의 다른 알림 훅이 모두 실행됩니다. 여러 파일에 완전히 동일한 훅이 있으면 한 번만 실행됩니다. 훅은 기본 제공 알림과도 함께 작동합니다. 두 알림을 모두 받는다면 Local notifications를 notifications_disabled로 설정하고 훅은 유지하세요.
• 알림이 너무 자주 온다면. Stop은 전체 작업이 완료됐을 때뿐 아니라 매 턴이 끝날 때마다 발생합니다.
• Cowork Island도 사용한다면. 위 코드 조각처럼 직접 추가한 훅은 각각 별도 항목으로 두고, ~/.perch/ 밖에 보관하세요. 앱은 /.perch/가 포함된 명령만 자체 명령으로 간주하며, 항목 전체를 교체합니다. 따라서 앱의 항목 안에 넣은 명령은 그 항목과 함께 제거됩니다.

• Claude Code 문서: 터미널 설정
• Claude Code 문서: 훅 참조
• Claude Code 문서: 훅 가이드
• Claude Code 문서: 설정 참조
• Claude Code 문서: 설정
• Claude Code 변경 이력
• Terminal 사용 설명서: 고급 설정
• Mac 자동화 스크립팅 가이드: 알림 표시
• Cowork Island FAQ 및 설치 가이드

출처 확인일: 2026년 10월 18일. 이 가이드는 Cowork Island를 만든 사람이 작성했습니다. 수정할 내용이 있으면 support@coworkisland.com으로 메일을 보내거나 GitHub에 이슈를 등록하세요.