Mac에서 클로드 코드 작업 완료 터미널 알림 설정 방법

맥에서 클로드 코드로 긴 작업을 맡겨 두고 다른 화면을 열어 일하다 보면 작업이 끝났다는 알림이 없어서 터미널 창을 계속 열어 확인하게 되는데요.

클로드 코드에서 작업이 완료되었을 때 터미널 벨, 훅(Hook), 스킬을 이용해 터미널 알림을 받을 수 있습니다.

1. 터미널 벨 기능으로 맥북 클로드 코드 알림 켜기

맥의 기본 터미널에서는 preferredNotifChannel을 terminal_bell로 지정하면 클로드 코드가 응답을 마치거나 권한을 물을 때 터미널 벨이 울립니다. 클로드 코드는 Ghostty, Kitty, iTerm2에서만 데스크톱 알림을 기본으로 보내며, macOS의 기본 터미널에서는 설정을 바꾸지 않으면 아무 알림도 나오지 않습니다.

터미널 벨을 켜려면, ~/.claude/settings.json에 아래 키를 최상위에 추가합니다.

{
  "preferredNotifChannel": "terminal_bell"
}

오래된 글에 자주 나오는 claude config set --global preferredNotifChannel terminal_bell 명령을 적용하면 Claude Code 2.1.310 이상 버전에서 unknown option '--global' 오류가 나타나니 설정 파일에 키를 직접 추가해야 합니다.

알림이 터미널 앱 쪽에서 허용돼 있어야 합니다.

터미널 벨 소리를 켜려면, 터미널 > 설정 > 프로필 > 고급에 진입해 ‘들을 수 있는 벨’, ‘배지 앱 및 윈도우 Dock 아이콘’, ‘백그라운드에 있을 때 바운스 앱 아이콘’ 항목을 켭니다.

설정을 마치면 클로드 코드에서 작업이 끝났을 때 소리 알림과 터미널 앱의 배지, 아이콘 바운스로 알림을 받을 수 있습니다.

2. 클로드 코드 훅으로 작업 완료 알림 등록하기

클로드 코드 훅은 응답이 끝나는 시점과 입력을 기다리는 시점에 셸 명령을 실행하므로, 두 이벤트에 osascript 알림 명령을 걸면 알림 센터에 배너와 소리가 나옵니다. Stop 훅은 응답을 마칠 때마다 실행되고, Notification 훅은 권한 확인이나 입력 대기처럼 클로드 코드가 알림을 보내는 순간에 실행됩니다.

알림 훅을 등록하려면, ~/.claude/settings.json의 hooks 항목에 아래 내용을 추가합니다.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"작업이 끝났어요\" with title \"Claude Code\" sound name \"Glass\"'",
            "timeout": 5
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"확인이 필요해요\" with title \"Claude Code\" sound name \"Ping\"'",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

sound name에는 /System/Library/Sounds 폴더의 파일 이름을 확장자 없이 적습니다. Glass, Ping 외에 Funk, Hero, Submarine 같은 이름을 쓸 수 있습니다.

Stop 훅은 응답마다 실행되므로 짧은 질문에도 알림이 옵니다. 긴 작업에만 알림을 받으려면 Stop 훅을 빼고 Notification 훅의 matcher를 idle_prompt로 지정합니다. 이 값은 클로드 코드가 응답을 마친 뒤 약 60초 동안 입력이 없을 때 실행됩니다.

등록한 훅은 클로드 코드 입력창에서 /hooks를 실행해 Stop과 Notification 아래에 나타나는지 확인합니다.

3. 클로드 코드 스킬로 훅 설정 맡기기

설정 파일을 직접 수정하기 부담스럽다면 클로드 코드의 update-config 스킬을 이용해 settings.json의 훅 설정을 대신 등록할 수 있습니다. 클로드 코드에 아래처럼 요청합니다.

~/.claude/settings.json의 hooks에 Stop 훅을 추가해서, 응답이 끝나면 osascript로 맥북 알림을 띄우게 설정

훅을 등록해도 알림이 도착하지 않을 수 있습니다. /hooks로 등록 여부를 확인하고, 새 세션을 시작한 뒤 짧은 작업을 하나 맡겨 알림이 실제로 오는지 직접 확인합니다.

4. osascript로 훅 등록 후 알림이 안올 때 알림 권한과 집중 모드 확인하기

osascript로 등록한 훅 알림이 조용하다면 먼저 Script Editor의 알림 권한을 확인합니다. Script Editor에 알림 권한이 없으면 명령이 오류 없이 실패하고 macOS도 권한을 묻지 않기 때문에, 훅이 정상 등록돼 있어도 알림이 오지 않습니다.

스크립트 편집기의 알림 권한을 확인하려면, 터미널에서 아래 명령을 한 번 실행합니다.

osascript -e 'display notification "테스트" with title "Claude Code" sound name "Glass"'

알림이 오지 않으면 스크립트 편집기에서 임시 스크립트를 1회 실행해 알림 설정을 활성화 하고 허용 설정해야 합니다.

Spotlight로 스크립트 편집기.app을 검색해 실행한 다음, 아래 코드를 붙여넣기하고 실행합니다. 그러면 알림 센터에 알림이 뜨는데, 클릭하면 알림 허용 여부를 선택할 수 있으며 시스템 설정 > 알림에 등록됩니다.

display notification "테스트" with title "Claude Code" sound name "Glass"

알림 허용을 켜면 클로드 코드에서 작업이 완료되었을 때 훅을 통해 알림을 받을 수 있게 됩니다. 만일 알림을 받을 수 없는 경우 원인별 증상과 해결은 아래 표와 같습니다.

마치며

훅이 등록돼 있어도 알림 센터를 거치는 명령은 macOS 권한을 따로 받아야 알림을 받을 수 있습니다.

반대로 터미널 벨은 알림 권한 없이 터미널 앱의 소리 설정만으로 동작하므로, 훅 알림이 울리지 않을 때 대체 수단으로 함께 켜 두면 클로드 코드 작업이 다 되었는지 확인하는 시간이 줄어듭니다.

설정을 바꾼 뒤에는 클로드 코드에 짧은 작업을 맡겨 알림이 실제로 오는지 한 번 확인합니다.

자주 묻는 질문