고급 사용법: 구성 팁과 모범 사례

학습 후 가능한 것

기본적으로 상위 세션만 알림을 받는 이유를 이해하고 알림 노이즈 줄이기
macOS 알림 효과음 사용자 정의로 다른 유형의 이벤트 구분
자동 감지 문제 해결을 위한 터미널 유형 수동 지정
회의나 집중 시간 중 방해받지 않도록 임시 무음 설정
시의성과 방해도 간의 균형을 맞춘 알림 전략 최적화

현재 겪고 있는 문제

알림 플러그인은 매우 편리하지만, 기본 설정은 모든 사람의 작업 습관에 적합하지 않을 수 있습니다:

모든 AI 하위 작업을 추적하고 싶지만 기본적으로 상위 세션만 알림
소수 사용 터미널을 사용하여 자동 감지 실패
회의 중 일시적으로 알림을 끄고 싶지만 매번 구성 파일을 수정하고 싶지 않음
다른 유형의 이벤트가 동일한 효과음을 사용하여 작업 완료와 오류를 구분하기 어려움

언제 이 방법을 사용해야 하나요

플러그인의 기본 사용법에 익숙해지고, 개인 워크플로우에 맞춰 알림 경험을 최적화하고 싶을 때 사용합니다.

핵심 원칙

알림 플러그인의 기본 설정은 신중하게 설계되었지만, 구성 파일을 통해 동작을 조정할 수 있습니다. 핵심 원칙은 다음과 같습니다:

노이즈 줄이기, 가치 높이기

상위 세션 필터링: 주요 작업만 알림, AI 내부 하위 작업 무시
포커스 인식: 터미널이 활성화되면 알림 중지, 중복 알림 방지
일괄 알림: 여러 작업이 동시에 완료되면 알림 병합

팁

모든 구성 항목은 구성 참조에 자세히 설명되어 있습니다. 이 과정은 실제 사용 팁과 모범 사례에 중점을 둡니다.

🎒 시작 전 준비

빠른 시작을 완료하고 첫 번째 알림을 성공적으로 받았는지 확인하세요.

따라 하기

1단계: 상위 세션 필터링 이해

이유

OpenCode 세션은 트리 구조입니다: 하나의 상위 세션에 여러 하위 세션이 있을 수 있습니다. 기본적으로 플러그인은 상위 세션 완료만 알리고 하위 작업의 알림 노이즈를 방지합니다.

구성 확인

구성 파일을 편집하세요:

bash

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

# Windows
%APPDATA%\opencode\kdco-notify.json

json

{
  "notifyChildSessions": false  // ← 기본값 false
}

예상 결과:

notifyChildSessions: false는 루트 세션만 알림을 의미합니다
AI 내부에서 실행되는 하위 도구 호출은 알림을 트리거하지 않습니다

하위 세션 알림 활성화 시기

각 하위 작업을 추적해야 하는 경우(예: 다단계 워크플로우 디버깅) true로 설정하세요:

json

{
  "notifyChildSessions": true  // ← 활성화하면 각 하위 작업마다 알림
}

주의

하위 세션 알림을 활성화하면 알림 빈도가 현저히 증가하므로 신중하게 사용하세요.

2단계: macOS 알림 효과음 사용자 정의

이유

다른 유형의 이벤트에 다른 효과음을 사용하면 알림을 보지 않고도 무슨 일이 일어났는지 알 수 있습니다.

사용 가능한 효과음 확인

macOS 시스템은 14가지 내장 효과음을 제공합니다:

효과음 이름	적용 시나리오	스타일
Glass	작업 완료(기본)	맑음
Basso	오류(기본)	낮음
Submarine	권한 요청(기본)	부드러움
Bottle	특수 이벤트	가벼움
Ping	일반 알림	간결
Pop	가벼운 이벤트	활기참
Purr	성공 이벤트	온화함
Blow	경고	긴급
Funk	특수 마커	독특함
Frog	알림	큼
Hero	중요 이벤트	웅장함
Morse	알림	리듬감
Sosumi	시스템 알림	클래식
Tink	완료	가벼움

효과음 사용자 정의

구성의 sounds 섹션을 수정하세요:

json

{
  "sounds": {
    "idle": "Ping",        // 작업 완료
    "error": "Blow",      // 오류(더 긴급)
    "permission": "Pop",   // 권한 요청(더 가벼움)
    "question": "Tink"    // 질문(선택 사항, 기본적으로 permission 효과음 사용)
  }
}

예상 결과:

수정 후 다른 유형의 이벤트는 해당 효과음을 재생합니다
sounds.question을 설정하지 않으면 sounds.permission 효과음을 사용합니다

팁

효과음은 macOS에서만 작동하며, Windows와 Linux는 시스템 기본 알림 효과음을 사용합니다.

3단계: 터미널 유형 수동 지정

이유

detect-terminal 라이브러리는 37개 이상의 터미널을 지원하지만, 소수 사용 터미널이나 사용자 정의 빌드 버전은 인식되지 않을 수 있습니다.

현재 감지된 터미널 확인

현재 감지 결과를 직접 볼 수는 없지만 로그를 통해 판단할 수 있습니다:

bash

# OpenCode UI는 플러그인 시작 로그를 표시합니다

"Terminal detection failed"와 같은 메시지가 보이거나 알림이 포커스되지 않으면 수동으로 지정해야 할 수 있습니다.

터미널 수동 지정

구성에 terminal 필드를 추가하세요:

json

{
  "terminal": "wezterm"  // 터미널의 소문자 이름 사용
}

지원되는 터미널 이름

일반적으로 사용되는 터미널 이름(대소문자 구분 없음):

터미널	구성 값
Ghostty	`"ghostty"`
Kitty	`"kitty"`
iTerm2	`"iterm"` 또는 `"iterm2"`
WezTerm	`"wezterm"`
Alacritty	`"alacritty"`
macOS Terminal	`"terminal"` 또는 `"apple_terminal"`
Hyper	`"hyper"`
VS Code 터미널	`"code"` 또는 `"code-insiders"`

예상 결과:

수동으로 지정한 후 macOS 포커스 감지 및 클릭 포커스 기능이 정상 작동합니다
지정이 무효하면 플러그인은 조용히 실패하고 자동 감지로 되돌아갑니다

4단계: 알림 임시 무음

이유

회의, 코드 리뷰 또는 집중 시간 동안 일시적으로 알림을 받고 싶지 않을 수 있습니다.

무음 시간 사용

매일 특정 시간대(예: 야간)에 방해받지 않으려면 무음 시간을 구성하세요:

json

{
  "quietHours": {
    "enabled": true,
    "start": "22:00",  // 밤 10시
    "end": "08:00"     // 다음 날 아침 8시
  }
}

자정을 넘는 시간 지원

무음 시간은 자정을 넘을 수 있습니다(예: 22:00-08:00):

json

{
  "quietHours": {
    "enabled": true,
    "start": "22:00",
    "end": "08:00"     // 22:00 - 다음 날 08:00
  }
}

예상 결과:

무음 시간 내 모든 이벤트는 알림을 보내지 않습니다
시간 외에는 정상 알림이 복원됩니다

팁

시간 형식은 HH:MM(24시간제)이어야 합니다(예: "22:30").

5단계: 알림 전략 균형 조정

이유

기본 설정은 이미 최적화되어 있지만, 워크플로우에 따라 조정할 수 있습니다.

기본 전략 요약

구성 항목	기본값	효과
`notifyChildSessions`	`false`	상위 세션만 알림
`quietHours.enabled`	`false`	무음 시간 비활성화

팁

포커스 감지 기능(터미널 활성화 시 알림 중지)은 하드코딩되어 있으며, 구성으로 끌 수 없습니다.

권장 구성 조합

시나리오 1: 최소 방해 추구(기본)

json

{
  "notifyChildSessions": false
}

시나리오 2: 모든 작업 추적

json

{
  "notifyChildSessions": true
}

주의

이 설정은 알림 빈도를 현저히 증가시키므로 세분화된 모니터링이 필요한 시나리오에 적합합니다.

시나리오 3: 야간 무음

json

{
  "notifyChildSessions": false,
  "quietHours": {
    "enabled": true,
    "start": "22:00",
    "end": "08:00"
  }
}

예상 결과:

시나리오에 따라 알림 동작에 현저한 차이가 있습니다
점진적으로 조정하여 가장 적합한 구성을 찾으세요

확인점 ✅

구성을 완료한 후 다음 내용을 확인하세요:

확인 항목	확인 방법
상위 세션 필터링	하위 작업이 포함된 AI 작업을 트리거하고 "Ready for review" 알림 하나만 수신
효과음 사용자 정의	작업 완료, 오류, 권한 요청을 각각 트리거하고 다른 효과음 듣기
터미널 오버라이드	macOS에서 알림을 클릭하면 터미널 창이 올바르게 상단에 표시됨
무음 시간	무음 시간 내 이벤트를 트리거하고 알림을 받지 않음

일반적인 문제

구성 변경이 적용되지 않음

문제: 구성 파일을 수정한 후 알림 동작이 변경되지 않습니다.

원인: OpenCode는 플러그인 또는 OpenCode 자체를 다시 시작해야 할 수 있습니다.

해결: OpenCode CLI 또는 OpenCode UI를 다시 시작하세요.

효과음이 재생되지 않음

문제: 사용자 정의 효과음을 설정했지만 여전히 기본 효과음입니다.

원인:

효과음 이름 철자 오류
macOS 플랫폼이 아님

해결:

효과음 이름이 지원 목록에 있는지 확인(대소문자 구분)
macOS 시스템을 사용 중인지 확인

터미널 오버라이드가 작동하지 않음

문제: terminal 필드를 설정했지만 알림을 클릭해도 포커스되지 않습니다.

원인:

터미널 이름 오류
터미널 프로세스 이름이 구성 값과 일치하지 않음

해결:

소문자 이름 시도
지원되는 터미널 목록 확인

과정 요약

이 과정에서는 opencode-notify의 고급 사용법과 모범 사례를 학습했습니다:

상위 세션 필터링: 기본적으로 루트 세션만 알림, 하위 작업 노이즈 방지
효과음 사용자 정의: macOS에서 14가지 효과음 사용자 정의, 이벤트 유형 구분
터미널 오버라이드: 터미널 유형 수동 지정, 자동 감지 문제 해결
임시 무음: quietHours로 무음 시간 설정
전략 균형: 워크플로우에 따라 구성 조정, 시의성과 방해도 균형

핵심 원칙: 노이즈 줄이기, 가치 높이기. 기본 설정은 이미 최적화되어 있으므로 대부분의 경우 수정할 필요가 없습니다.

다음 과정 예고

다음 과정에서는 **문제 해결**을 학습합니다.
학습할 내용:
알림이 표시되지 않을 때 해결 방법
포커스 감지 실패 시 문제 해결
일반적인 오류 메시지 해석
플랫폼별 문제 해결 방법

부록: 소스 코드 참조

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

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

기능	파일 경로	행 번호
상위 세션 감지	`src/notify.ts`	205-214
구성 스키마	`src/notify.ts`	30-68
기본 구성	`src/notify.ts`	56-68
macOS 효과음 목록	`README.md`	81

중요 상수:

DEFAULT_CONFIG: 기본 구성 값
TERMINAL_PROCESS_NAMES: 터미널 이름에서 macOS 프로세스 이름으로의 매핑 테이블

중요 함수:

isParentSession(): 세션이 상위 세션인지 확인
loadConfig(): 사용자 구성 로드 및 병합

고급 사용법: 구성 팁과 모범 사례 ​

학습 후 가능한 것 ​

현재 겪고 있는 문제 ​

언제 이 방법을 사용해야 하나요 ​

핵심 원칙 ​

🎒 시작 전 준비 ​

따라 하기 ​

1단계: 상위 세션 필터링 이해 ​

2단계: macOS 알림 효과음 사용자 정의 ​

3단계: 터미널 유형 수동 지정 ​

4단계: 알림 임시 무음 ​

5단계: 알림 전략 균형 조정 ​

확인점 ✅ ​

일반적인 문제 ​

구성 변경이 적용되지 않음 ​

효과음이 재생되지 않음 ​

터미널 오버라이드가 작동하지 않음 ​

과정 요약 ​

다음 과정 예고 ​

부록: 소스 코드 참조 ​

고급 사용법: 구성 팁과 모범 사례

학습 후 가능한 것

현재 겪고 있는 문제

언제 이 방법을 사용해야 하나요

핵심 원칙

🎒 시작 전 준비

따라 하기

1단계: 상위 세션 필터링 이해

2단계: macOS 알림 효과음 사용자 정의

3단계: 터미널 유형 수동 지정

4단계: 알림 임시 무음

5단계: 알림 전략 균형 조정

확인점 ✅

일반적인 문제

구성 변경이 적용되지 않음

효과음이 재생되지 않음

터미널 오버라이드가 작동하지 않음

과정 요약

다음 과정 예고

부록: 소스 코드 참조