Use Notification (agent-notify)

cd ~/Projects/oss
git clone https://github.com/paultendo/agent-notify.git
cd agent-notify
chmod +x ./install-agent-notify.sh
./install-agent-notify.sh

macOS에서는 terminal-notifier가 없어도 기본 알림은 동작할 수 있습니다. 다만 클릭 복귀 경험은 제한될 수 있습니다.

2. Codex에 notify hook 연결

가장 쉬운 방법:

Terminal

$HOME/bin/agent-notify --setup-codex

이 명령은 ~/.codex/config.toml에 notify 설정을 추가합니다.

실제로는 아래와 같은 형태가 들어갑니다.

~/.codex/config.toml

notify = ["$HOME/bin/agent-notify"]

이미 notify 항목이 있다면 전체를 덮어쓰지 말고, 현재 값이 agent-notify를 가리키는지만 확인하면 됩니다.

3. 수동으로 설정할 때

자동 설정 대신 직접 넣고 싶다면 ~/.codex/config.toml에 notify를 추가합니다.

~/.codex/config.toml

model = "gpt-5.4"
model_reasoning_effort = "high"

notify = ["$HOME/bin/agent-notify"]

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

agent-notify는 프로젝트 루트의 .agent-notify.env를 읽습니다.

예를 들어 이 저장소에서만 긴 작업에만 알림을 주고 싶다면:

.agent-notify.env

CODEX_NOTIFY_MIN_DURATION=30
CODEX_NOTIFY_GIT_BRANCH=1
CODEX_NOTIFY_SAY=1

자주 쓰는 값:

CODEX_NOTIFY_MIN_DURATION: N초 이상 걸린 작업만 알림
CODEX_NOTIFY_GIT_BRANCH=1: 알림에 현재 브랜치 표시
CODEX_NOTIFY_SAY=1: TTS 읽기
CODEX_NOTIFY_SOUND: 완료 사운드 변경
CODEX_NOTIFY_APPROVAL_SOUND: 승인 요청 사운드 변경
CODEX_NOTIFY_WEBHOOK: Slack, Discord, Telegram, ntfy 같은 외부 알림 연동

5. 동작 확인

기본 테스트:

Terminal

$HOME/bin/agent-notify --test
$HOME/bin/agent-notify --test-approval

그 다음 Codex를 다시 시작하고, 시간이 조금 걸리는 작업 하나를 실행해 봅니다.

정상이라면:

작업 완료 시 완료 알림이 옵니다.
권한 승인이 필요할 때 별도 알림이 옵니다.

중요

notify 설정을 바꾼 뒤에는 실행 중인 Codex 세션을 재시작해야 반영됩니다.

트러블슈팅

알림이 안 올 때

~/.codex/config.toml의 notify 경로 확인
Codex 재시작 여부 확인
macOS 알림 권한 확인
terminal-notifier 설치 확인
terminal-notifier 알림 권한 확인

macOS에서 클릭 복귀가 어색할 때

agent-notify는 macOS에서 terminal-notifier가 없으면 osascript로 fallback 할 수 있습니다. 이 경우 알림은 오더라도 클릭 복귀 동작이 제한될 수 있습니다.

terminal-notifier를 별도로 설치했다면 macOS 시스템 설정에서 해당 앱의 알림/접근성 권한도 같이 확인합니다.

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

프로젝트 루트에 .agent-notify.env를 두면 됩니다. CODEX_NOTIFY_*와 CODEX_SILENT 값을 저장소별로 다르게 둘 수 있습니다.

Use Notification (agent-notify)

소개

언제 쓰면 좋은가

준비물

terminal-notifier 설치

1. agent-notify 설치