빠른 시작: 5분 만에 opencode-notify 시작하기

학습 후 할 수 있는 것

• 3분 안에 opencode-notify 플러그인 설치 완료
• 첫 번째 데스크톱 알림 트리거하여 설치 성공 확인
• 다양한 설치 방법의 차이점과 적용 시나리오 이해

현재 겪고 있는 문제

AI에게 작업을 맡긴 후 다른 창으로 전환하여 작업합니다. 이제 30초마다 다시 돌아가서 확인합니다: 완료되었나? 오류가 발생했나? 아니면 권한을 기다리고 있나? opencode-notify는 바로 이 문제를 해결하기 위해 만들어졌습니다.

이러한 반복적인 전환은 사고를 방해하고 시간을 낭비합니다.

언제 이 방법을 사용하나요

다음 시나리오에서 opencode-notify를 활성화하세요:

• AI가 작업을 실행하는 동안 다른 애플리케이션으로 자주 전환하는 경우
• AI가 필요로 할 때 즉시 알림을 받고 싶은 경우
• 집중력을 유지하면서 중요한 이벤트를 놓치지 않고 싶은 경우

핵심 아이디어

opencode-notify의 작동 원리는 간단합니다: OpenCode의 이벤트를 모니터링하고 중요한 순간에 네이티브 데스크톱 알림을 보냅니다.

알림을 보내는 경우:

• ✅ 작업 완료 (Session idle)
• ✅ 실행 오류 (Session error)
• ✅ 권한 필요 (Permission updated)

알림을 보내지 않는 경우:

• ❌ 각 하위 작업 완료 (너무 시끄러움)
• ❌ 터미널이 포커스된 상태의 모든 이벤트 (터미널을 보고 있으므로 알림 불필요)

🎒 시작하기 전 준비사항

사전 요구사항

• OpenCode 설치 완료
• 사용 가능한 터미널 (macOS Terminal, iTerm2, Windows Terminal 등)
• macOS/Windows/Linux 시스템 (모두 지원)

따라하기

1단계: 설치 방법 선택

opencode-notify는 두 가지 설치 방법을 제공합니다:

방법	적용 시나리오	장점	단점
OCX 패키지 매니저	대부분의 사용자	원클릭 설치, 자동 업데이트, 완전한 의존성 관리	OCX 먼저 설치 필요
수동 설치	특수한 요구사항	완전한 제어, OCX 불필요	의존성 및 업데이트 수동 관리 필요

권장사항: OCX 설치를 우선 사용하면 더 편리합니다.

2단계: OCX를 통한 설치 (권장)

2.1 OCX 패키지 매니저 설치

OCX는 OpenCode의 공식 플러그인 패키지 매니저로, 플러그인을 편리하게 설치, 업데이트 및 관리할 수 있습니다.

OCX 설치:

curl -fsSL https://ocx.kdco.dev/install.sh | sh

예상 결과: 설치 스크립트가 진행 상황을 표시하고 마지막에 설치 성공 메시지를 표시합니다.

2.2 KDCO Registry 추가

KDCO Registry는 opencode-notify 등 여러 유용한 플러그인을 포함하는 플러그인 저장소입니다.

registry 추가:

ocx registry add https://registry.kdco.dev --name kdco

예상 결과: "Registry added successfully" 또는 유사한 메시지가 표시됩니다.

선택사항: 전역 설정

모든 프로젝트에서 동일한 registry를 사용하려면 --global 매개변수를 추가하세요:

ocx registry add https://registry.kdco.dev --name kdco --global

2.3 opencode-notify 설치

플러그인 설치:

ocx add kdco/notify

예상 결과:

✓ Added kdco/notify to your OpenCode workspace

3단계: 전체 워크스페이스 일괄 설치 (선택사항)

완전한 경험을 원한다면 KDCO 워크스페이스를 설치할 수 있습니다. 포함 내용:

• opencode-notify (데스크톱 알림)
• 백그라운드 에이전트 (Background Agents)
• 전문 에이전트 (Specialist Agents)
• 계획 도구 (Planning Tools)

워크스페이스 설치:

ocx add kdco/workspace

예상 결과: 여러 컴포넌트가 성공적으로 추가되었다는 메시지가 표시됩니다.

4단계: 설치 확인

설치 완료 후 알림을 트리거하여 설정이 올바른지 확인해야 합니다.

확인 방법 1: AI에게 작업 완료 요청

OpenCode에 다음을 입력하세요:

1부터 10까지의 합을 계산한 다음 5초 후에 결과를 알려주세요.

다른 창으로 전환하여 몇 초간 작업하면 데스크톱 알림이 나타납니다.

확인 방법 2: 설정 파일 확인

설정 파일이 존재하는지 확인하세요:

# macOS/Linux
cat ~/.config/opencode/kdco-notify.json

# Windows PowerShell
type $env:USERPROFILE\.config\opencode\kdco-notify.json

예상 결과:

• 파일이 없는 경우 → 기본 설정 사용 중 (정상)
• 파일이 있는 경우 → 사용자 정의 설정 표시

5단계: 수동 설치 (대체 방법)

OCX를 사용하지 않으려면 수동으로 설치할 수 있습니다.

5.1 소스 코드 복사

opencode-notify의 소스 코드를 OpenCode 플러그인 디렉토리에 복사하세요:

# 소스 코드를 독립 디렉토리로 복사
mkdir -p ~/.opencode/plugin/kdco-notify
cp src/notify.ts ~/.opencode/plugin/kdco-notify/
cp -r src/plugin/kdco-primitives ~/.opencode/plugin/kdco-notify/

5.2 의존성 설치

필요한 의존성을 수동으로 설치하세요:

cd ~/.opencode/plugin/
npm install node-notifier detect-terminal @opencode-ai/plugin @opencode-ai/sdk

주의사항

• 의존성 관리: node-notifier와 detect-terminal을 수동으로 설치 및 업데이트해야 합니다
• 업데이트 어려움: 매번 업데이트 시 소스 코드를 수동으로 다시 복사해야 합니다
• 권장하지 않음: 특수한 요구사항이 없다면 OCX 설치를 권장합니다

체크포인트 ✅

위 단계를 완료한 후 다음을 확인하세요:

• [ ] OCX 설치 성공 (ocx --version으로 버전 번호 출력 확인)
• [ ] KDCO Registry 추가 완료 (ocx registry list에 kdco 표시)
• [ ] opencode-notify 설치 완료 (ocx list에 kdco/notify 표시)
• [ ] 첫 번째 데스크톱 알림 수신
• [ ] 알림에 올바른 작업 제목 표시

단계가 실패한 경우:

• 문제 해결에서 도움 받기
• OpenCode가 정상적으로 실행되는지 확인
• 시스템이 데스크톱 알림을 지원하는지 확인

주의사항

일반적인 문제 1: 알림이 표시되지 않음

원인:

• macOS: 시스템 알림이 꺼져 있음
• Windows: 알림 권한이 부여되지 않음
• Linux: notify-send가 설치되지 않음

해결 방법:

플랫폼	해결 방법
macOS	시스템 설정 → 알림 → OpenCode → 알림 허용
Windows	설정 → 시스템 → 알림 → 알림 켜기
Linux	libnotify-bin 설치: sudo apt install libnotify-bin

일반적인 문제 2: OCX 설치 실패

원인: 네트워크 문제 또는 권한 부족

해결 방법:

1. 네트워크 연결 확인
2. sudo로 설치 (관리자 권한 필요)
3. 설치 스크립트를 수동으로 다운로드하여 실행

일반적인 문제 3: 의존성 설치 실패

원인: Node.js 버전 비호환

해결 방법:

• Node.js 18 이상 버전 사용
• npm 캐시 정리: npm cache clean --force

이번 강의 요약

이번 강의에서 완료한 내용:

• ✅ OCX 패키지 매니저 설치
• ✅ KDCO Registry 추가
• ✅ opencode-notify 플러그인 설치
• ✅ 첫 번째 데스크톱 알림 트리거
• ✅ 수동 설치 방법 이해

핵심 포인트:

1. opencode-notify는 네이티브 데스크톱 알림을 사용하여 창 전환 빈도를 줄입니다
2. OCX는 권장 설치 방법으로 의존성과 업데이트를 자동으로 관리합니다
3. 기본적으로 상위 세션만 알림하여 하위 작업 노이즈를 방지합니다
4. 터미널이 포커스된 상태에서는 알림을 자동으로 억제합니다

다음 강의 예고

다음 강의에서는 **작동 원리**를 학습합니다.

배울 내용:

• 플러그인이 OpenCode 이벤트를 모니터링하는 방법
• 스마트 필터링 메커니즘의 작동 흐름
• 터미널 감지 및 포커스 인식 원리
• 다양한 플랫폼의 기능 차이

---

부록: 소스 코드 참조

클릭하여 소스 코드 위치 보기

업데이트 시간: 2026-01-27

기능	파일 경로	행 번호
플러그인 메인 진입점	src/notify.ts	1-407
설정 로드	src/notify.ts	90-114
---	---	---
---	---	---
---	---	---
알림 전송	src/notify.ts	280-308
터미널 감지	src/notify.ts	145-176
무음 시간대 확인	src/notify.ts	181-199
기본 설정	src/notify.ts	30-48

주요 상수:

• DEFAULT_CONFIG.sounds.idle = "Glass": 작업 완료 기본 사운드
• DEFAULT_CONFIG.sounds.error = "Basso": 오류 기본 사운드
• DEFAULT_CONFIG.sounds.permission = "Submarine": 권한 요청 기본 사운드
• DEFAULT_CONFIG.notifyChildSessions = false: 기본적으로 상위 세션만 알림

주요 함수:

• NotifyPlugin(): 플러그인 진입 함수, 이벤트 핸들러 반환
• loadConfig(): 설정 파일 로드, 기본값 병합
• sendNotification(): 네이티브 데스크톱 알림 전송
• detectTerminalInfo(): 터미널 유형 및 Bundle ID 감지
• isQuietHours(): 현재 시간이 무음 시간대인지 확인
• isParentSession(): 상위 세션인지 판단
• isTerminalFocused(): 터미널이 포그라운드 창인지 감지