Claude Code나 Codex가 끝나면 알림 받는 방법

에이전트가 끝났다고 알려 주는 원리

두 도구 모두 정해진 순간에 내 명령을 실행할 수 있어요. 알림이란 결국 그게 전부예요. Claude Code는 이걸 훅, Codex는 notify라고 불러요. 그 명령이 하는 일(소리 재생, 배너 표시, 화면 깜빡임)은 에이전트가 멈추거나 입력을 요청할 때 일어나요.

Claude Code: 내장 알림

Claude Code는 작업이 끝나거나 권한 확인을 기다릴 때 스스로 데스크톱 알림을 보낼 수 있어요. Anthropic 문서에 따르면 Ghostty와 Kitty에서는 바로 작동해요. iTerm2에서는 한 번만 켜 주세요.

1. iTerm2 → Settings → Profiles → Terminal.
2. Notification Center Alerts를 체크하세요.
3. Filter Alerts를 클릭하고 Send escape sequence-generated alerts를 켜세요.

tmux 안에서 Claude Code를 쓰나요? ~/.tmux.conf에 set -g allow-passthrough on을 추가하세요. 안 그러면 알림이 터미널까지 오지 않아요. Claude Code가 알려 주는 방식(예: 터미널 벨)은 /config 설정에서도 고를 수 있어요.

출처: Claude Code 문서: 터미널 설정

Claude Code: 소리를 내는 훅

Apple의 터미널, VS Code 등 다른 터미널에서는 훅을 쓰면 돼요. 훅은 ~/.claude/settings.json(모든 프로젝트) 또는 .claude/settings.json(한 프로젝트)에 들어가요. 중요한 이벤트는 두 가지예요.

• Stop: Claude가 답변을 끝냈어요.
• Notification: Claude가 나를 필요로 해요(권한 확인, 또는 입력을 기다리는 중).

아래 설정은 두 경우 모두 macOS 사운드를 재생해요. 설정 파일에 합쳐 넣으세요(이미 있는 내용은 그대로 두고요).

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

배너가 더 좋다면 이 명령을 대신 쓰세요(Anthropic 예시와 같아요).

osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'

Claude Code에서 /hooks를 입력하면 설정된 훅을 볼 수 있어요. 새 훅은 저장한 뒤 시작한 세션부터 적용돼요. /System/Library/Sounds/의 사운드는 무료로 써도 돼요: Glass, Ping, Pop, Purr, Submarine 등.

출처: 훅 레퍼런스 · 훅 가이드

Codex: notify 설정

Codex CLI는 매 턴이 끝날 때마다 내 프로그램을 실행해요. ~/.codex/config.toml의 notify로 설정하죠. Codex는 턴 정보를 담은 JSON을 마지막 인자로 넘기는데(type은 agent-turn-complete), 단순한 소리 명령이라면 무시해도 돼요.

notify = ["sh", "-c", "afplay /System/Library/Sounds/Glass.aiff"]

notify는 최상위 키라서 파일의 어떤 [section]보다도 위에 넣어야 해요. Codex에는 터미널 UI에 내장된 알림([tui] 아래 notifications)도 있는데, 터미널 자체 알림이나 벨을 써요. 배너가 보일지는 터미널에 따라 달라요.

Codex의 notify는 턴이 끝날 때 실행돼요. Claude Code의 Notification 훅처럼 “승인이 필요해요” 이벤트가 따로 있지는 않아요.

출처: Codex 문서: 고급 설정

Clacky의 에이전트 알림: 설정 없이 똑같이

JSON이나 TOML을 고치고 싶지 않다면, Clacky(Mac 메뉴 막대 앱)에 에이전트 알림이 있어요. 위와 같은 훅을 쓰기 때문에 화면을 지켜보거나 터미널을 읽는 건 없어요.

1. Clacky 대시보드 → 에이전트 알림을 여세요.
2. Claude Code나 Codex 옆의 설정…을 클릭하세요. Clacky가 추가할 줄을 정확히 보여 줘요. 훅 추가를 클릭하세요. 원래 파일의 백업도 옆에 남겨 둬요(settings.json.clacky-backup).
3. 테스트 알림 보내기를 클릭해서 두 소리를 들어 보세요.

이런 걸 얻어요.

• 완료(올라가는 화음)와 확인 필요(톡톡 두 번과 물음표 같은 소리)에 서로 다른 소리, 에이전트마다 다섯 가지 목소리 중에서 골라요.
• 선택 사항으로 약 1초 동안 화면 가장자리에 은은한 글로우. 클릭이 통과되고 녹화에는 절대 안 나와요.
• 앞에 있을 땐 조용히(에이전트의 터미널이 활성 앱일 때 무음)와 통화 중엔 조용히(마이크 사용 중 무음), 둘 다 기본으로 켜져 있어요.
• 메뉴 막대에 세션마다 점 하나: 작업 중, 대기 중, 완료. 클릭하면 그 터미널을 앞으로 가져와요.
• 깨어 있기 → 에이전트가 끝날 때까지로 Mac이 잠들어서 긴 작업이 멈추는 일을 막아요.

Claude Code는 모든 터미널과 Claude 앱의 Code 탭에서 작동해요. Codex는 CLI에서 작동하고 완료 소리를 받아요(Codex는 “확인 필요” 이벤트를 보내지 않아요). Codex 설정에 이미 notify 줄이 있으면 Clacky는 그걸 바꾸지 않고 그대로 둔 채 알려 줘요. 제거…는 Clacky가 넣은 줄만 지워요.

아무 일도 안 일어난다면

• 세션을 다시 시작하세요. 훅은 세션이 시작될 때 읽히기 때문에, 이미 돌고 있던 세션은 알림을 보내지 않아요.
• 파일이 제대로 읽히는지 확인하세요. settings.json에 쉼표 하나만 빠져도 모든 훅이 멈춰요. 아무 JSON 검사기에 붙여 넣어 보세요.
• 명령만 따로 테스트하세요. 터미널에서 afplay /System/Library/Sounds/Glass.aiff를 실행해 보세요. 소리가 안 나나요? 출력 기기와 볼륨을 확인하세요.
• 배너가 안 뜨나요? 시스템 설정 → 알림에서 터미널(osascript라면 스크립트 편집기)을 확인하고, 집중 모드도 확인하세요.
• 소리가 두 번 나나요? 설정이 두 개 있는 거예요(예: 직접 만든 훅과 Clacky의 훅). 하나만 남기세요.