Use Notification (abc-notify)

소개

Claude Code를 여러 터미널 창에서 동시에 돌리면 어떤 창에서 응답이 끝났는지 놓치기 쉽습니다.

abc-notify는 Claude Code hook에 연결되어 작업 완료와 승인 요청 시 macOS 알림을 보냅니다. abc-notify-native까지 함께 설치되어 있으면 클릭 시 원래 세션 창으로 더 정확하게 복귀할 수 있습니다.

기본 터미널 알림보다 좋은 점은 Claude Code와 Codex를 한 도구로 같이 관리할 수 있고, 설치 후 doctor로 상태를 바로 점검할 수 있다는 점입니다.

언제 쓰면 좋은가

• Claude Code 세션을 여러 터미널 창에서 병렬 실행할 때
• 다른 Space나 다른 앱으로 이동해 둔 상태에서 결과만 빠르게 확인하고 싶을 때
• Claude Code와 Codex 알림 구성을 하나로 통일하고 싶을 때

준비물

• macOS
• Claude Code CLI
• terminal-notifier
• jq
• 선택: Swift toolchain (abc-notify-native를 직접 빌드할 때만)

기본 의존성 설치:

brew install terminal-notifier jq

1. abc-notify 설치

가장 쉬운 방법은 Homebrew입니다.

brew tap JHSeo-git/tap
brew install abc-notify

이 경로는 릴리스 아카이브와 함께 abc-notify-native도 설치합니다.

저장소 체크아웃 기준으로 설치하고 싶다면:

cd ~/Projects
git clone https://github.com/JHSeo-git/abc-notify.git
cd abc-notify
bash scripts/manual-install.sh

2. Claude Code hook 연결

자동 설정:

abc-notify setup claude

이 명령은 ~/.claude/settings.json에 필요한 hook들을 추가합니다.

직접 구성한다면 최소 예시는 아래와 같습니다.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "abc-notify init" }]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "abc-notify notify" }]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "abc-notify notify" }]
      }
    ],
    "SessionEnd": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "abc-notify cleanup" }]
      }
    ]
  }
}

3. 어떻게 동작하나

1. SessionStart Claude Code를 시작한 세션 정보를 저장합니다.
2. Stop 응답이 끝났을 때 완료 알림을 보냅니다.
3. Notification 권한 요청이나 입력 대기처럼 사용자 확인이 필요한 경우에도 알림을 보냅니다.
4. SessionEnd 세션 임시 상태를 정리합니다.
5. 알림 클릭 abc-notify-native가 있으면 더 정확한 창 복귀를 시도하고, 없으면 앱 활성화 기반 fallback으로 동작합니다.

4. 확인 방법

기본 검사:

abc-notify doctor

그 다음:

1. 터미널 A에서 Claude Code를 실행합니다.
2. 시간이 조금 걸리는 작업을 요청합니다.
3. 터미널 B나 다른 Space로 이동합니다.
4. 작업이 끝나면 macOS 알림이 옵니다.
5. 알림을 클릭했을 때 원래 Claude Code 세션으로 복귀하면 정상입니다.

5. 프로젝트별로 알림 동작 바꾸기

전역 ~/.abc-notify.env, 프로젝트별 ./.abc-notify.env를 사용할 수 있습니다.

예시:

TERMINAL_APP=iTerm2,Terminal,WezTerm
NOTIFY_SOUND=Glass
NOTIFY_TITLE_CLAUDE="Claude Code · blog.seonest.net"

트러블슈팅

알림이 전혀 안 올 때

• abc-notify doctor 출력 확인
• terminal-notifier, jq 설치 여부 확인
• macOS 시스템 설정에서 알림 허용 확인
• ~/.claude/settings.json 문법 오류 확인
• NOTIFY_DISABLED=true가 설정되지 않았는지 확인

클릭 시 원래 창 복귀가 약할 때

Homebrew 설치 경로라면 보통 abc-notify-native가 함께 들어옵니다. 저장소 기준 수동 설치라면 설치 스크립트를 다시 실행하거나, 네이티브 헬퍼가 실제 검색 경로에 있는지 확인합니다.

정확한 터미널 앱 감지가 흔들리면 TERMINAL_APP을 명시적으로 넣는 편이 안전합니다.

TERMINAL_APP=iTerm2

저장소마다 다르게 동작시키고 싶을 때

프로젝트 루트에 .abc-notify.env를 두면 됩니다. 프로젝트 설정이 전역 설정보다 우선합니다.

관련 문서

• Claude Code Hooks
• Claude Code Terminal Setup
• abc-notify GitHub 저장소